使用 Pycco 生成代码文档

网友投稿 778 2022-05-29

目录

项目设置

生成一些文档

生成的文档

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 ===

使用 Pycco 生成代码文档

然后在文档中生成一个标题。

文档字符串:

""" 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小时内删除侵权内容。

上一篇:知识图谱系列(一)十分钟入门知识图谱
下一篇:Gin + Swagger快速生成API文档
相关文章