Django Sphinx 自动模块 -- 基础知识

Question

我有一个项目，里面有几个比较大的应用程序，而且设置和应用文件是分开的。

目录结构大致是这样的：

项目名称

• _init_.py
• apps
• _init_.py
• app1
• app2
• 3rdparty
• _init_.py
• lib1
• lib2
• settings
• _init_.py
• installed_apps.py
• path.py
• templates.py
• locale.py
• ...
• urls.py

每个应用程序都是这样的结构

• _init_.py
• admin
• _init_.py
• file1.py
• file2.py
• models
• _init_.py
• model1.py
• model2.py
• tests
• _init_.py
• test1.py
• test2.py
• views
• _init_.py
• view1.py
• view2.py
• urls.py

我想知道怎么用Sphinx自动生成文档？

我希望能做到这样的效果：对于每个设置模块或INSTALLED_APPS（不以django.*或3rdparty.*开头），根据文档字符串给我自动生成文档。

而且在提交代码之前，自动生成文档并运行测试。

顺便说一下，我试着手动做.rst文件，使用了

.. automodule:: module_name
   :members:

但是对于这么大的项目来说，这样做太麻烦了，而且对设置部分也不适用。

有没有什么自动生成的方法或者其他解决方案？

我并不一定要用Sphinx，有没有更好的解决办法？

Answer 1

django-sphinx-autodoc 可能会对你有帮助。

根据文档内容：

它是如何工作的

首先，把 generate_autodoc.py 文件复制到你的项目目录里，然后运行它。

这个文件会自动扫描你在 INSTALLED_APP 中列出的每个应用里的所有 .py 文件，然后把模块信息添加到你的 DS_ROOT/modules.rst 文件中。

这样，你就能看到你的应用被分成两类：

• 内部应用 是指位于你项目目录中的应用
• 外部应用 是指在你的 pythonpath 中的应用（最好是在你的虚拟环境中）

好的实践

在你应用的 __init__.py 文件中添加一个文档字符串来描述它。django-sphinx-autodoc 会自动为你提取这个信息。

Answer 2

1. 可以查看这个链接：自动生成所有Python包内容的文档。

2. 即将发布的Sphinx 1.1版本中，包含了一个叫做sphinx-apidoc.py的脚本。