【待更新】Python 项目文档,从0到1


(Frederic Chan) #1

在我刚开始做 EveryClass每课 的时候,无论是对于 Python 还是对于真正的项目开发,我都是一个纯粹的新手。这一年来,真的学习了特别多的知识,让我有可能去把这个项目进行优化。今天要说的,就是一个重要的部分——文档。

要让一个开源项目成为一个能够让大家都真正参与、贡献的项目,文档是必不可少的——想象一下当你阅读一份没有注释的代码是什么感受吧,没人想去做这样的事情。在 Python 社区中,著名的文档工具是 Sphinx。

什么是 Sphinx

Sphinx 是 pocoo 团队开发的工具(pocoo团队开发了很多优秀的产品:如Flask, Jinja2等等),它已经用来生成Python官方文档和大多数流行的Python包的文档。它以更容易的方式从 Python 代码中自动产生 Python 文档。

不要把它想的过于智能了!『自动产生』的意思并不是用人工智能去阅读你的代码。Sphinx 只能翻译reStructuredText(rst)文件,也就意味着你需要的是维护 reStructuredText 风格的文档或代码注释。


使用 Sphinx 完成工作

显然,要求程序员(尤其是在开源社区)每次更新代码内注释时顺便更新单独一份 reStructuredText 文档显然是不可行的。幸运的是,Sphinx 有一个类似 javadoc 的扩展,叫做 autodoc。可以自动从你的代码中提取出 reStructuredText 并生成文档,避免手动维护两份文档。为了使用它,你需要用一种特别的方式格式化你的文档。一个典型的注释格式如下:

def _validate(cls, method, resource=None):
"""Return ``True`` if the the given *cls* supports the HTTP *method* found
on the incoming HTTP request.
 
:param cls: class associated with the request's endpoint
:type cls: :class:`sandman.model.Model` instance
:param string method: HTTP method of incoming request
:param resource: *cls* instance associated with the request
:type resource: :class:`sandman.model.Model` or None
:rtype: bool
 
"""
if not method in cls.__methods__:
    return False
 
class_validator_name = 'validate_' + method
 
if hasattr(cls, class_validator_name):
    class_validator = getattr(cls, class_validator_name)
    return class_validator(resource)
 
return True

安装 Sphinx

Sphinx不同的版本可能会产生不同的HTML输出。通过将其安装在你的 virtualenv 内,你可以以受控的方式升级你的文档。(使用操作系统的包管理工具安装是极其错误的行为)

一般来说,文档位于 docs 文件夹。在项目的根目录运行以下命令:

mkdir docs
cd docs/
sphinx-quickstart

随后,你将会被询问一连串问题:

这些选项都很好理解,但是请一定要打开 autodoc;如果你有几个project需要交叉引用的话,intersphinx 可能会很有用;viewcode 会添加从 module listings 到 source code 的引用,这可能对用户很有用。

之后将产生一个包含许多文件的 docs 文件夹。其中有一个叫 conf.py 的文件,这是你的文档配置文件。你还会发现一个 Makefile,方便你用一条简短的命令( make html )构建 HTML 文档。


ReadTheDocs

参考

  1. 以正确的方式开源 Python 项目(推荐阅读)