使用Sphinx在单个模块上生成自动文档的Python代码？

Question

我正在开发一个只有一个 .py 模块的 Python 库，并尝试从文档字符串生成文档。我已经安装了 Sphinx 并运行了 spinx-quickstart 脚本，但当我尝试在文档目录下运行以下命令时：

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

但是它只是说：

../cffiwrap.py is not a directory.

是否有其他Sphinx脚本可以自动记录单个文件？我考虑只针对..运行它，但是我想它会进入我的测试目录并尝试从我的单元测试生成文档。

- Isaac Freeman

Answer 1

这篇博客文章似乎展示了一种为单个模块生成自动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

- S.A.

Answer 2

手册上说：

sphinx-apidoc [选项] -o 打包目录 [路径名...]

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

因此，请尝试：

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

test_dir 是你的测试文件所在的目录。

- Steve Barnes

---

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