生成镜像包和模块树的第一个文件和目录

Question

我正在尝试为我的图书馆生成文档。由于库目录结构很大，我希望 Sphinx 生成 .rst 文件作为反映包和模块结构的嵌套目录。

库结构：

pyflocker/
├── __init__.py
├── ciphers/
│   ├── __init__.py
│   ├── backends/
│   │   ├── __init__.py
│   │   ├── _asymmetric.py
│   │   ├── _symmetric.py
│   │   ├── cryptodome_/
│   │   │   ├── AES.py
│   │   │   ├── ChaCha20.py
│   │   │   ├── ECC.py
│   │   │   ├── Hash.py
│   │   │   ├── RSA.py
│   │   │   ├── __init__.py
│   │   │   ├── _serialization.py
│   │   │   └── _symmetric.py
│   │   └── cryptography_/
│   │       ├── AES.py
│   │       ├── Camellia.py
│   │       ├── ChaCha20.py
│   │       ├── DH.py
│   │       ├── ECC.py
│   │       ├── Hash.py
│   │       ├── RSA.py
│   │       ├── __init__.py
│   │       ├── _serialization.py
│   │       └── _symmetric.py
│   ├── base.py
│   ├── exc.py
│   ├── interfaces/
│   │   ├── AES.py
│   │   ├── Camellia.py
│   │   ├── ChaCha20.py
│   │   ├── DH.py
│   │   ├── ECC.py
│   │   ├── Hash.py
│   │   ├── RSA.py
│   │   └── __init__.py
│   └── modes.py
└── locker.py

到目前为止，我一直在使用 sphinx-apidoc -e -o ... 在 docs/source/ 文件夹中生成文档。但这并没有像预期的那样工作。

预期结果：

作为嵌套目录生成的文档。这些文件已被删除以仅保留 backbone。

docs/source/
└── ciphers/
    └── backends/
        ├── cryptodome_/
        └── cryptography_/

实际结果：

保留整个模块名称。

docs/source/
├── ...  # skipping boilerplate files
├── pyflocker.ciphers.backends.cryptodome_.AES.rst
├── pyflocker.ciphers.backends.cryptodome_.ChaCha20.rst
├── pyflocker.ciphers.backends.cryptodome_.ECC.rst
├── pyflocker.ciphers.backends.cryptodome_.Hash.rst
├── pyflocker.ciphers.backends.cryptodome_.RSA.rst
├── pyflocker.ciphers.backends.cryptodome_.rst
├── pyflocker.ciphers.backends.cryptography_.AES.rst
├── pyflocker.ciphers.backends.cryptography_.Camellia.rst
├── pyflocker.ciphers.backends.cryptography_.ChaCha20.rst
├── pyflocker.ciphers.backends.cryptography_.DH.rst
├── pyflocker.ciphers.backends.cryptography_.ECC.rst
├── pyflocker.ciphers.backends.cryptography_.Hash.rst
├── pyflocker.ciphers.backends.cryptography_.RSA.rst
├── pyflocker.ciphers.backends.cryptography_.rst
├── pyflocker.ciphers.backends.rst
├── pyflocker.ciphers.base.rst
├── pyflocker.ciphers.exc.rst
├── pyflocker.ciphers.interfaces.AES.rst
├── pyflocker.ciphers.interfaces.Camellia.rst
├── pyflocker.ciphers.interfaces.ChaCha20.rst
├── pyflocker.ciphers.interfaces.DH.rst
├── pyflocker.ciphers.interfaces.ECC.rst
├── pyflocker.ciphers.interfaces.Hash.rst
├── pyflocker.ciphers.interfaces.RSA.rst
├── pyflocker.ciphers.interfaces.rst
├── pyflocker.ciphers.modes.rst
├── pyflocker.ciphers.rst
├── pyflocker.locker.rst
└── pyflocker.rst

有什么方法可以将文档生成为目录树吗？

Answer 1

您指定的目前不可能。

sphinx-apidoc 不会创建镜像您的 package/file 结构的目录。
sphinx-apidoc 不会将 .rst 文件分发到几个镜像您的 package/file 结构的目录中。

注意 sphinx-apidoc 签名，您可以为模块指定一个输入路径，为 .rst 个文件指定一个输出路径：

Synopsis

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]

您必须编写自己的脚本以递归到您的文件系统中，并针对每个 package/directory 和 <MODULE_PATH> 镜像 <OUTPUT_PATH> 执行一次 sphinx-apidoc。

这可能看起来 counter-intuitive，但 Python 理念是：

The Zen of Python - PEP 20

Flat is better than nested.

可以说，让 sphinx-apidoc 生成 .rst 文件的点名镜像 package/module 结构更方便，因为您可以一目了然地了解包的概况，并且它倾向于节省点击。

如果你想在之后将一些 .rst 文件组织到目录中，可以 link 它们，但是在撰写本文时，无法使用 sphinx-apidoc 在单次执行中。

Answer 2

可以使用 sphinx-nested-apidoc 来做到这一点。它反映原始包结构并生成适当的文件。

请注意，它不会编辑文件或其中的链接。它只是重命名或移动它们。

生成镜像包和模块树的第一个文件和目录

Generate rst files and directories mirroring the package and module tree

python

python-sphinx

sphinx-apidoc

库结构：

预期结果：

实际结果：