问题描述
我正在尝试为我的图书馆生成文件。由于库目录结构很大,我希望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
解决方法
您目前无法指定。
-
sphinx-apidoc
将不会创建镜像您的包/文件结构的目录。 -
sphinx-apidoc
不会在与您的包/文件结构类似的几个目录中分发.rst
文件。
请注意sphinx-apidoc
签名,您可以为模块指定一个输入路径,为.rst
文件指定一个输出路径:
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]
您必须编写自己的脚本才能递归到文件系统中,并使用sphinx-apidoc
镜像<MODULE_PATH>
对每个包/目录执行一次<OUTPUT_PATH>
。
这似乎违反直觉,但是Python的哲学是:
扁平比嵌套更好。
可以说,sphinx-apidoc
生成带有虚线名称的.rst
文件以反映软件包/模块结构会更加方便,因为您可以一眼看到软件包的概况,而且往往可以节省点击次数
如果您以后想要将一些.rst
文件组织到目录中,可以将它们链接起来,但是在撰写本文时,不可能在文件中使用sphinx-apidoc
自动生成这样的树。一次执行。
可以使用 sphinx-nested-apidoc 来实现。 它镜像原始包结构并生成适当的文件。
请注意,它不会编辑文件或其中的链接。它只是重命名或移动它们。