sphinx-autogen

概要

sphinx-autogen [选项] <源文件> …

描述

sphinx-autogen 是一个用于自动生成 Sphinx 源文件的工具，它使用 autodoc 扩展，来文档化包含在 autosummary 列表中的条目。

源文件 是一个或多个 reStructuredText 文档的路径，这些文档包含带有 :toctree: 选项设置的 autosummary 条目。源文件 可以是一个 fnmatch 风格的模式。

选项

-o <输出目录>

放置输出文件的目录。如果它不存在，则会被创建。默认为传递给 :toctree: 选项的值。

-s <后缀>, --suffix <后缀>

用于生成文件的默认后缀。默认为 rst。

-t <模板目录>, --templates <模板目录>

自定义模板目录。默认为 None。

-i, --imported-members

文档化导入的成员。

-a, --respect-module-all

精确地文档化模块 __all__ 属性中的成员。

--remove-old

移除输出目录中不再生成的文件。

示例

给定以下目录结构

docs
├── index.rst
└── ...
foobar
├── foo
│   └── __init__.py
└── bar
    ├── __init__.py
    └── baz
        └── __init__.py

并假设 docs/index.rst 包含以下内容

Modules
=======

.. autosummary::
   :toctree: modules

   foobar.foo
   foobar.bar
   foobar.bar.baz

如果你运行以下命令

$ PYTHONPATH=. sphinx-autogen docs/index.rst

那么以下存根文件将被创建在 docs 中

docs
├── index.rst
└── modules
    ├── foobar.bar.rst
    ├── foobar.bar.baz.rst
    └── foobar.foo.rst

并且每个文件都将包含一个 autodoc 指令和其他一些信息。

参见

sphinx-build(1), sphinx-apidoc(1)