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

Question

I'm working on a Python library that only has a single .py module and I'm trying to generate documentation for it from the docstrings. I have Sphinx set up and ran through the spinx-quickstart script, but when I try to run (while in the docs directory)

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

But it just says:

../cffiwrap.py is not a directory.

Is there some other Sphinx script to autodoc a single file? I thought about just running it against .. but then I figured it would run in to my tests directory and try to generate docs from my unit tests...

Answer 1

The manual says:

sphinx-apidoc [options] -o packagedir [pathnames ...]

where pathnames are the directories to exclude.

So try:

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

where test_dir is where your tests live.

Answer 2

This short blog post seems to show an alternative way to generate an automatic api doc for a single module. Copied here for convenience and persistence:

Place the conf.py file at the same directory as your module:

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}

Add this index.rst next to it

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

.. automodule:: <project>
   :members:

Finally, replace <project> with your module name, pip install sphinx and run:

sphinx-build -b html . _build