1

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

有没有办法将文档生成为目录树？

4

2 回答 2

1

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

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

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

概要

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

您必须编写自己的脚本以递归到您的文件系统，并使用mirroringsphinx-apidoc为每个包/目录执行一次。<MODULE_PATH><OUTPUT_PATH>

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

Python 之禅 - PEP 20

平面优于嵌套。

sphinx-apidoc可以说，生成带有点名的文件来反映包/模块结构会更方便.rst，因为您可以一目了然地了解包，而且它往往会节省点击。

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

于 2020-11-03T12:49:07.440 回答
1

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

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

于 2021-01-22T20:37:52.037 回答