生成镜像包和模块树的rst文件和目录 库结构：预期结果：实际结果：

如何解决生成镜像包和模块树的rst文件和目录 库结构：预期结果：实际结果：

我正在尝试为我的图书馆生成文件。由于库目录结构很大，我希望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

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

解决方法

您目前无法指定。

1. sphinx-apidoc将不会创建镜像您的包/文件结构的目录。
2. sphinx-apidoc不会在与您的包/文件结构类似的几个目录中分发.rst文件。

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

Synopsis

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

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

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

The Zen of Python - PEP 20

扁平比嵌套更好。

可以说，sphinx-apidoc生成带有虚线名称的.rst文件以反映软件包/模块结构会更加方便，因为您可以一眼看到软件包的概况，而且往往可以节省点击次数

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

,

可以使用 sphinx-nested-apidoc 来实现。 它镜像原始包结构并生成适当的文件。

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