Sphinx sphinx-quickstart sphinx-apidoc auto generate API documents

原创

已于 2024-06-28 15:28:18 修改 · 764 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#sphinx #autodoc #python

于 2024-06-28 15:13:20 首次发布

How to use Sphinx?

Sphinx uses reStructuredText as its markup language.

The process of Sphinx generating documents is like this:

Project source code (Python or other supported languages)->reStructuredText files ->documents (HTML or other supported format)

Sphinx provides two command-line tools: sphinx-quickstart and sphinx-apidoc.

sphinx-quickstart sets up a source directory and creates a default configuration, conf.py, and a master document, index.rst, which serves as a welcome page of a document.
- After running sphinx-quickstart, the layout of the docs folder looks like:
- ```
docs
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst
```

sphinx-apidoc generates reStructuredText files to document from all found modules.

After running sphinx-apidoc -f -o source/ ../trees/ the layout of the docs folder looks like:
- modules.rst and trees.rst and so on being added to source folder.

docs
├── Makefile
├── build
│   └── doctrees
│       ├── environment.pickle
│       └── index.doctree
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    ├── modules.rst
    ├── trees.bin.rst
    ├── trees.binary_trees.rst
    └── trees.rst

In short, we use these two tools to generate Sphinx source code, i.e., reStructuredText files,

and we modify these reStructuredText files,

and finally use Sphinx to build excellent documents.