Python：在单个模块上使用 Sphinx 生成 autodoc？答案

【问题标题】：Python: Generate autodoc with Sphinx on a single module?Python：在单个模块上使用 Sphinx 生成 autodoc？
【发布时间】：2013-09-09 16:32:18
【问题描述】：

我正在开发一个只有一个 .py 模块的 Python 库，并且我正在尝试从文档字符串中为其生成文档。我已经设置了 Sphinx 并运行了 spinx-quickstart 脚本，但是当我尝试运行时（在 docs 目录中）

sphinx-apidoc ../cffiwrap.py -o .

但它只是说：

../cffiwrap.py is not a directory.

是否有其他的 Sphinx 脚本可以自动编辑单个文件？我想过只针对.. 运行它，但后来我认为它会运行到我的测试目录并尝试从我的单元测试中生成文档...

【问题讨论】：

标签： python python-sphinx autodoc sphinx-apidoc

【解决方案1】：

手册说：

sphinx-apidoc [选项] -o packagedir [路径名...]

其中路径名是要排除的目录。

那就试试吧：

sphinx-apidoc -o . .. ../test_dir

test_dir 是您的测试所在的位置。

【讨论】：

手册确实提到了一种排除路径名的方法，但我认为您的语法不正确。无论如何，我会尝试只排除测试目录。

【解决方案2】：

这个简短的blog post 似乎展示了另一种为单个模块生成自动 api 文档的方法。为了方便和持久，复制到这里：

将conf.py 文件放在与您的模块相同的目录中：

import os
import sys

# enable autodoc to load local modules
sys.path.insert(0, os.path.abspath("."))

project = "<project>"
copyright = "year, author"
author = "author"
extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
templates_path = ["_templates"]
html_theme = "alabaster"
html_static_path = ["_static"]
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None)
}
html_theme_options = {"nosidebar": True}

在它旁边添加这个index.rst

<project>
=========

.. automodule:: <project>
   :members:

最后，将 <project> 替换为您的模块名称 pip install sphinx 并运行：

sphinx-build -b html . _build

【讨论】：