生成反映包和模块树的rst文件和目录。

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/文件夹中生成文档。但这不像预期的那样有效。

预期成果：

作为嵌套目录生成的文档。文件已被移除，以便仅保留主干。

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

使用狮身人面像-巢状可以做到这一点。它镜像原始包结构并生成适当的文件。

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

Answer 2

您指定的内容目前不可能实现。

1. sphinx-apidoc不会创建映射包/文件结构的目录。
2. sphinx-apidoc不会沿着镜像包/文件结构的几个目录分发.rst文件。

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

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

您必须编写自己的脚本才能递归到您的文件系统中，并对每个包/目录执行一次sphinx-apidoc，其中包含<MODULE_PATH>镜像<OUTPUT_PATH>。

这似乎违反了直觉，但是Python的哲学是：

Python 20的禅宗 平比嵌套好。

可以说，让sphinx-apidoc生成带有虚名的、映射包/模块结构的.rst文件更为方便，因为您一目了然地了解了包的概况，并且易于保存单击。

如果您想以后将一些.rst文件组织到目录中，那么可以将它们链接起来，但是在编写本文时，不可能在一次执行中使用sphinx-apidoc自动生成这样的树。