使用 Pycco 生成代碼文檔

目錄

項目設置

生成一些文檔

生成的文檔

Make It Fancy

為整個項目自動生成文檔

非 Python 文件的文檔

項目級文檔如何？

Regeneration

作為開發人員，我們喜歡編寫代碼，盡管當時對我們來說很有意義，但我們必須考慮我們的受眾。有人必須閱讀、使用和/或維護所述代碼。三個月后，它可能是另一個開發人員、客戶或我們未來的自己。

即使是像 Python 這樣優美的語言有時也很難理解。因此，作為非常關心我們的程序員同事（或者更有可能是因為我們的老板希望我們這樣做）的優秀編程公民，我們應該編寫一些文檔。

但是有規則：

編寫文檔不能爛（即我們不能使用 MS Word）。

編寫文檔必須盡可能輕松。

編寫文檔不能要求我們離開我們最喜歡的文本編輯器/IDE。

編寫文檔不得要求我們對最終演示文稿進行任何格式化或完全關心。

這就是Pycco 的用武之地：

“Pycco”是 Docco 的 Python 端口：原始的快速而骯臟的、百行長的、文學編程風格的文檔生成器。它生成 HTML，在代碼旁邊顯示您的注釋。注釋通過 Markdown 和 SmartyPants 傳遞，而代碼通過 Pygments 傳遞以進行語法高亮顯示。

所以基本上這意味著 Pycco 可以為我們自動生成看起來不錯的代碼文檔。Pycco 還遵守上述代碼文檔的四項規則。那么什么是不愛呢？讓我們來看看如何使用它的一些示例。

對于本文，我從一個用Django編寫的簡單 TODO 應用程序開始，您可以從repo 中獲取它。該應用程序允許用戶將項目添加到列表中并在完成后刪除它們。這個應用程序可能不會為我贏得 Webby，但它應該滿足本文的目的。

請注意，repo 中的文件已經包含最終代碼，已經記錄在案。不過，您仍然可以創建單獨的文檔文件，所以請隨意克隆 repo 并跟隨我。

項目設置

克隆回購：

$ git clone git@github.com:mjhea0/django-todo.git

設置虛擬環境：

$ cd django-todo $ virtualenv --no-site-packages venv $ source venv/bin/activate

安裝要求：

$ pip install -r requirements.txt

同步數據庫：

$ cd todo $ python manage.py syncdb

生成一些文檔

入門很簡單：

$ pip install pycco

然后要運行它，您可以使用如下命令：

$ pycco todos/*.py

請注意，您可以通過這種方式指定單個文件或文件目錄。在我們的 TODO 存儲庫上執行上述命令會產生以下結果：

pycco = todo/todos/__init__.py -> docs/__init__.html pycco = todo/todos/models.py -> docs/models.html pycco = todo/todos/tests.py -> docs/tests.html pycco = todo/todos/views.py -> docs/views.html

換句話說，它生成 html 文件（每個 python 文件一個）并將它們全部轉儲到“docs”目錄中。對于較大的項目，您可能需要使用 -p 選項來保留原始文件路徑。

例如：

pyccoo todo/todos/*.py -p

會產生：

pycco = todo/todos/__init__.py -> docs/todo/todos/__init__.html pycco = todo/todos/models.py -> docs/todo/todos/models.html pycco = todo/todos/tests.py -> docs/todo/todos/tests.html pycco = todo/todos/views.py -> docs/todo/todos/views.html

請注意，它已將 todos 應用程序的文檔存儲在“docs/todo/todos”子文件夾下。通過這樣做，瀏覽大型項目的文檔會容易得多，因為文檔結構將與代碼結構相匹配。

生成的文檔

pycco 的目的是生成一個兩列文檔，左側帶有注釋，右側與后續代碼對齊。因此，在我們還沒有注釋的models.py類上調用 pycco將生成一個如下所示的頁面：

您會注意到左側的列（應該是注釋的地方）是空白的，而右側則顯示了代碼。我們可以通過添加docstring來更改models.py以通過將以下代碼添加到models.py來獲得更有趣的文檔。

from django.db import models # === Models for Todos app === class ListItem(models.Model): """ The ListItem class defines the main storage point for todos. Each todo has two fields: text - stores the text of the todo is_visible - used to control if the todo is displayed on screen """ text = models.CharField(max_length=300) is_visible = models.BooleanField()

使用上面的代碼片段，pycco 找到了以下行：

# === Models for Todos app ===

然后在文檔中生成一個標題。

文檔字符串：

""" The ListItem class defines the main storage point for todos. Each todo has two fields: text - stores the text of the todo is_visible - used to control if the todo is displayed on screen """

Pycco 使用文檔字符串來生成文檔。再次運行 pycco 后的最終結果將是：

如您所見，左側的文檔與右側的代碼很好地對齊。這使得查看代碼和了解正在發生的事情變得非常容易。

Pycco 還識別代碼中以 a 開頭的單行注釋#以生成文檔。

Make It Fancy

但 pycco 并不止于此。它還允許使用 Markdown 自定義注釋格式。作為示例，讓我們在views.py文件中添加一些注釋。首先，讓我們在views.py的頂部放置一個文檔字符串：

""" All the views for our todos application Currently we support the following 3 views: 1. **Home** - The main view for Todos 2. **Delete** - called to delete a todo 3. **Add** - called to add a new todo """ from django.http import HttpResponse from django.shortcuts import render_to_response from django.template import RequestContext from todos.models import ListItem def home(request): items = ListItem.objects.filter(is_visible=True) return render_to_response('home.html', {'items': items}, context_instance = RequestContext(request)) # ... code omitted for brevity ...

這將生成如下報告：

我們還可以在文件之間甚至在同一文件內添加鏈接。可以使用[[filename.py]]或添加鏈接[[filename.py#section]]，它們將呈現為帶有文件名的鏈接。讓我們更新views.py以在列表中每個項目的末尾添加一些鏈接：

""" All the views for our todos application Currently we support the following 3 views: 1. **Home** - The main view for Todos (jump to section in [[views.py#home]] ) 2. **Delete** - called to delete a todo ( jump to section in [[views.py#delete]] ) 3. **Add** - called to add a new todo (jump to section in [[views.py#add]]) """ from django.http import HttpResponse from django.shortcuts import render_to_response from django.template import RequestContext # defined in [[models.py]] from todos.models import ListItem # === home === def home(request): items = ListItem.objects.filter(is_visible=True) return render_to_response('home.html', {'items': items}, context_instance = RequestContext(request)) # === delete === def delete(request): # ... code omitted for brevity ...

如您所知，建立鏈接有兩個組成部分。首先，我們必須在我們的文檔中定義一個部分。您可以看到我們已經使用代碼定義了 home 部分# === home ===。創建部分后，我們可以使用代碼鏈接到它[[views.py#home]]。我們還插入了一個指向模型文檔文件的鏈接，代碼如下：

# defined in [[models.py]]

最終結果是如下所示的文檔：

請記住，因為 pycco 允許使用標記語法，您還可以使用完整的 html。所以發瘋:)

為整個項目自動生成文檔

如何使用 pycco 為整個項目生成文檔可能并不明顯，但如果您使用 bash 或 zsh 或任何支持全局的 sh，它實際上非常簡單，您只需運行如下命令：

$ pycco todo/**/*.py -p

這將為.pytodo的任何/所有子目錄中的所有文件生成文檔。如果你在 Windows 上，你應該可以用 cygwin、git bash 或 power sh 來做到這一點。

非 Python 文件的文檔

Pycco 還支持其他幾種文件類型，這對于經常使用一種以上文件類型的 Web 項目很有幫助。在撰寫本文時，受支持文件的完整列表是：

.coffee?- CoffeeScript

.pl?- Perl

.sql?- SQL

.c?- C

.cpp?- C++

.js?- JavaScript

.rb?- Ruby

.py?- Python

.scm?- Scheme

.lua?- Lua

.erl?- Erlang

.tcl?- Tcl

.hs?- Haskell

這應該涵蓋您的文檔需求。所以只要記住寫一些注釋，讓 pycco 輕松地為您生成漂亮的代碼文檔。

項目級文檔如何？

通常項目除了代碼文檔之外還有其他要求——比如自述文件、安裝文檔、部署文檔等。使用 pycco 生成該文檔也很好，這樣我們就可以始終堅持使用一個工具。好吧，此時，pycco 將僅處理具有上述列表中擴展名的文件。但是沒有什么可以阻止您創建readme.py或installation.py文件并使用 pycco 生成文檔。您所要做的就是將您的文檔放在一個文檔字符串中，然后 pycco 將生成它并為您提供完整的降價支持。所以想象一下，如果在你的項目目錄的底部你有一個名為的文件夾project_docs，其中包含：

install_docs.py

project_readme.py

deployment.py

然后你可以運行以下命令：

$ pycco project_docs/*.py -p

這會在您的“docs/project_docs 目錄”中添加適當的 html 文件。當然，這可能有點小技巧，但它確實允許您使用一種工具為您的項目生成所有文檔。

Regeneration

Pycco 還有一個絕招：自動重新生成文檔。換句話說，您可以讓 pycco 監視您的源文件，并在每次保存源文件時自動重新生成必要的文檔。如果您嘗試在評論中添加一些自定義降價/html 并希望確保其正確呈現，這將非常有用。隨著自動文檔重新生成運行，您只需進行更改、保存文件并刷新瀏覽器，無需在其間重新運行 pycco 命令。為此，您需要安裝看門狗：

$ pip install watchdog

Watchdog 是監聽文件變化的模塊。因此，一旦安裝完成，只需執行如下命令：

$ pycco todo/**/*.py -p --watch

它將運行 pycco 并保持運行，直到您用Ctrl+C停止它為止。只要它正在運行，它就會重新生成有關源文件每次更改的文檔。簡單的文檔如何？

Pycoo 是迄今為止我遇到的最簡單、最直接的 Python 代碼文檔工具。

HTML Python

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。