3

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

目录结构是这样的：

项目名

  • _初始化_.py
  • 应用
  • _初始化_.py
  • 应用程序1
  • 应用程序2
  • 第三方
  • _初始化_.py
  • 库1
  • 库2
  • 设置
  • _初始化_.py
  • 安装的应用程序.py
  • 路径.py
  • 模板.py
  • 语言环境.py
  • ...
  • 网址.py

每个应用程序都是这样

  • _初始化_.py
  • 行政
  • _初始化_.py
  • 文件1.py
  • 文件2.py
  • 楷模
  • _初始化_.py
  • 模型1.py
  • 模型2.py
  • 测试
  • _初始化_.py
  • 测试1.py
  • 测试2.py
  • 意见
  • _初始化_.py
  • 视图1.py
  • 视图2.py
  • 网址.py

如何使用 Sphinx 自动生成文档？

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

并在 git commit 之前自动生成文档并运行测试

顺便提一句。我试着用手工制作 .rst 文件

.. automodule:: module_name
   :members:

但是对于这么大的项目来说很糟糕，而且它不适用于设置

有没有自动生成方法之类的？

我没有绑定到 Sphinx，是否有更好的解决方案来解决我的问题？

4

2 回答 2

2

  1. 请参阅为所有 Python 包内容自动生成文档。

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

于 2011-03-14T16:12:44.367 回答
1

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

从文档中：

这个怎么运作

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

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

然后，您将看到您的应用程序分为 2 个不同的类别：

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

良好实践

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

于 2013-06-12T12:20:04.703 回答