程式文件自動產生器 – Pycco

程式文件自動產生器 – Pycco

這篇文章主要說明當程式已經加入適當註解後，

有沒有什麼工具可以幫助直接產生 HTML技術說明文件?

我們主要介紹一個Python小工具Pycco來達成這件事情。

Pycco 這個工具除了可以為 Python程式註解自動產生文件外，

還可以為 .cpp – C++ 與.js – javascript產生文件。

Pycoo 產生的文件

首先先看看 Pycoo 產生的HTML文件結果為何?

如下圖所示，左邊為原本程式註解，右邊為原始程式。

也就是說 Pycoo 是將程式中的程式註解抽離放在 HTML的左邊，而程式碼放在HTML的右邊

如果這樣的文件適合使用的話，接下來我們就安裝使用

如何安裝 Pycoo?

因為這是一個 python 套件，所以安裝 python是必須的。

利用 python 的 PIP 可以安裝 pycco

pip install pycco

產生說明文件檔

pycco     example.py

pycco = example.py  -> docs/example.html

所產生的說明文件就會在 docs 路徑下

Python 程式註解技巧

如果 python 程式註解運用一些小技巧可以讓說明文件產生的更完整。

技巧1: 善用文件註解 “”” …..”””

“””
1. Wait for select-lanauge options == 3
2. wait for “Account” appear
3. Click Account

“””
技巧2:function/method name的註解
# === method or function name ===

這個技巧會讓產生說明文件時，段落呈現更明顯。參考以下範例：

[pastacode lang=”python” message=”” highlight=”1,6″ provider=”manual”]

    # === test account link ===


    def test_account_link(self):

        """
                1. Wait for select-lanauge options == 3
                2. wait for "Account" appear
                3. Click Account

        """


        WebDriverWait(self.driver, 10) \
            .until(lambda s: s.find_element_by_id("select-language").get_attribute("length") == "3")

[/pastacode]

技術參考資料

http://fitzgen.github.io/pycco/
https://github.com/fitzgen/pycco