django sphinx automodule - 基础知识

Question

我有一个包含多个大型应用的项目，其中设置和应用文件被拆分。

目录结构就像这样：

PROJECT_NAME

• __初始化__。PY
• 应用
  • __初始化__。PY
  • APP1
  • APP2
• 的3rdParty
  • __初始化__。PY
  • LIB1
  • LIB2
• 设置
  • __初始化__。PY
  • installed_apps.py
  • path.py
  • templates.py
  • locale.py
  • ...
• urls.py

每个应用都是那样

• __初始化__。PY
• 管理员
  • __初始化__。PY
  • file1.py
  • file2.py
• 模型
  • __初始化__。PY
  • model1.py
  • model2.py
• 测试
  • __初始化__。PY
  • test1.py
  • test2.py
• 的观点
  • __初始化__。PY
  • view1.py
  • view2.py
• urls.py

如何使用sphinx为其自动生成文档？

我想要那样的东西 对于每个设置模块或INSTALLED_APPS（不是以django。*或3rdparty。*开头）给我一个基于docstring的自动文档输出

和autogen文档并在git commit之前运行测试

顺便说一句。 我尝试用

手动执行.rst文件

.. automodule:: module_name
   :members:

但这个大项目很糟糕， 它不适用于设置

是否有自动方法或什么？

我不喜欢狮身人面像，对我的问题有更好的解决方案吗？

Answer 1

1. 请参阅Automatically Generating Documentation for All Python Package Contents。

2. 即将发布的Sphinx 1.1版本包含sphinx-apidoc.py脚本。

Answer 2

django-sphinx-autodoc可能会有所帮助。

来自文档：

  

如何运作

     

将generate_autodoc.py文件复制到项目目录中，然后   执行它。

     

它会抓取列出的每个应用程序中的所有.py个文件   INSTALLED_APP，然后在DS_ROOT/modules.rst。

中添加自动模块      

然后，您会看到您的应用程序分为两类：

     

  
• 内部应用程序是位于项目中的应用程序   目录
  
• 外部应用程序是一个位于您的应用程序中的应用程序   pythonpath（最好是你的virtualenv）
  

     

良好做法

     

在应用程序的__init__.py文件中添加docstring来描述它。   django-sphinx-autodoc会自动为你刮掉它。