CODEWITHSUNDEEP
pythonpython-sphinxsphinx-apidoc
arunanshub
arunanshub

Reputation: 658

Generate rst files and directories mirroring the package and module tree

I'm trying to generate documentation for my library. Since the library directory structure is quite big, I want Sphinx to generate the .rst files as a nested directory that mirrors the package and module structure.

The library structure:

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

Till now I was using sphinx-apidoc -e -o ... to generate the documentation within the docs/source/ folder. But this doesn't work as expected.

Expected Results:

Documentation generated as a nested directory. The files have been removed to keep the backbone only.

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

Actual results:

The whole module name is retained.

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

Is there any way to generate the doc as a directory tree?

Upvotes: 1

Views: 1377

Answers (2)

arunanshub
arunanshub

Reputation: 658

It is possible to do so using sphinx-nested-apidoc. It mirrors the original package structure and generates appropriate files.

Note that it does not edit the files or the links within it. It just renames or moves them.

Upvotes: 1

bad_coder
bad_coder

Reputation: 12890

What you specify isn't currently possible.

  1. sphinx-apidoc will not create directories mirroring your package/file structure.
  2. sphinx-apidoc will not distribute .rst files along several directories mirroring your package/file structure.

Notice the sphinx-apidoc signature, you can specify one input path for modules, and one output path for the .rst files:

Synopsis

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

You'll have to write your own script to recurse into your file system and execute sphinx-apidoc once for every package/directory with <MODULE_PATH> mirroring <OUTPUT_PATH>.

This may seem counter-intuitive, however the Python philosophy is:

The Zen of Python - PEP 20

Flat is better than nested.

Arguably it is more convenient to have sphinx-apidoc produce the .rst files with dotted names mirroring the package/module structure, because you get an overview of the packages at a glance and it tends to save clicking.

If you want to organize some .rst files into directories afterwards it is possible to link them, at the time of this writing it is however not possible to generate such a tree automatically using sphinx-apidoc in a single execution.

Upvotes: 1

Related Questions