Skip to main content

sphinx-nested-apidoc: When flattened is not enough

Project description

When flattened is not enough.

CI Coverage Black isort PyPI - Python Version Documentation Status

Installation

Use pip or pip3 to install sphinx-nested-apidoc

pip install sphinx-nested-apidoc

or

pip3 install sphinx-nested-apidoc

Introduction

sphinx-apidoc is a great tool for generating documentation, but it does not replicate the directory structure of your package. sphinx-nested-apidoc aims to solve that problem.

Tutorial

Let’s say we have the following directory structure of our package:

mymodule/
├── fruits/
│   ├── __init__.py
│   ├── mango.py
│   ├── pear.py
├── animals/
│   ├── special/
│   │   ├── __init__.py
│   │   ├── doggo.py
│   │   └── catto.py
│   ├── __init__.py
│   ├── monke.py
│   └── chimp.py
├── __init__.py
├── base.py
└── exceptions.py

And we want to generate documentation for this package in some directory docs/.

Let’s see the difference.

Using sphinx-apidoc we get

We use the following command:

sphinx-apidoc -o docs/ mymodule/ -e

It generates:

docs/
├── modules.rst
├── mymodule.animals.chimp.rst
├── mymodule.animals.monke.rst
├── mymodule.animals.rst
├── mymodule.animals.special.catto.rst
├── mymodule.animals.special.doggo.rst
├── mymodule.animals.special.rst
├── mymodule.base.rst
├── mymodule.exceptions.rst
├── mymodule.fruits.mango.rst
├── mymodule.fruits.pear.rst
├── mymodule.fruits.rst
└── mymodule.rst

This is not very clean, obviously.

Using sphinx-nested-apidoc we get

We use the following command:

sphinx-nested-apidoc -o docs/ mymodule/

It generates:

docs/
├── modules.rst
└── mymodule/
    ├── animals/
    │   ├── chimp.rst
    │   ├── index.rst
    │   ├── monke.rst
    │   └── special/
    │       ├── catto.rst
    │       ├── doggo.rst
    │       └── index.rst
    ├── base.rst
    ├── exceptions.rst
    ├── fruits/
    │   ├── mango.rst
    │   ├── pear.rst
    │   └── index.rst
    └── index.rst

Looks clean!

Want to name the package something else?

sphinx-nested-apidoc --package-name src -o docs/ mymodule/

It generates:

docs/
├── modules.rst
└── src/
    ├── animals/
    │   ├── chimp.rst
    │   ├── index.rst
    │   ├── monke.rst
    │   └── special/
    │       ├── catto.rst
    │       ├── doggo.rst
    │       └── index.rst
    ├── base.rst
    ├── exceptions.rst
    ├── fruits/
    │   ├── mango.rst
    │   ├── pear.rst
    │   └── index.rst
    └── index.rst

Note that mymodule has been renamed to src.

As a Sphinx Extension

You can also use this as a sphinx extension.

Create a file called docs/conf.py and configure it like this:

# ...
extensions = [
    "sphinx_nested_apidoc",
    # ...other extensions
]

# Name of the package directory.
sphinx_nested_apidoc_package_dir = "packagename"
# Name of the folder to put all the package documentation in. By default it is
# the name of the package itself.
sphinx_nested_apidoc_package_name = "src"
# ...

And then run:

sphinx-build docs docs/_build

Usage Details

usage: sphinx-nested-apidoc [-h] [-v | -q] [--version] [-f] [-n] -o DESTDIR
                            [--package-name PACKAGE_NAME] [-s SUFFIX]
                            [--implicit-namespaces]
                            module_path ...

Generates nested directory from sphinx-apidoc’s flattened files. It is simply a wrapper over sphinx-apidoc and you can pass additional arguments to it for extended configuration.

positional arguments:
module_path

Path to package to document.

...

Commands and flags to supply to sphinx-apidoc. Note that some arguments like –dry-run are ignored.

options:
-h, --help

show this help message and exit

-v, --verbose

Increase application verbosity. This option is repeatable and will increase verbosity each time it is repeated. This option cannot be used when -q/–quiet is used. (default: 3)

-q, --quiet

Disable logging. This option cannot be used when -v/–verbose is used. (default: False)

--version

show program’s version number and exit

-f, --force

Replace existing files. (default: False)

-n, --dry-run

Run the script without creating files (default: False)

-o, --output-dir

directory to place all output (default: None)

--package-name

Name of the directory to put the package documentation in. By default it is the name of the package itself. (default: None)

sphinx-apidoc options:
-s, --suffix

file suffix (default: rst)

--implicit-namespaces

interpret module paths according to PEP-0420 implicit namespaces specification (default: False)

Sphinx Extension Configuration

The following configuration values are used:

Option Name

Description

Default

Required?

sphinx_nested_apidoc_package_dir

This is where the package to document resides.

YES

sphinx_nested_apidoc_package_name

Name of the directory to put all the package documentation in. By default it is the name of the package itself.

None

sphinx_nested_apidoc_suffix

The suffix of the generated documentation files.

rst

sphinx_nested_apidoc_excluded_files

List of files (without extension) to exclude from modification/renaming.

index, modules

sphinx_nested_apidoc_module_first

put module documentation before submodule documentation.

False

sphinx_nested_apidoc_implicit_namespaces

interpret module paths according to PEP-0420 implicit namespaces specification.

False

Some additional details

What it does

  • As you saw earlier, it generates a nested directory from a flattened one.

  • Under the hood, it uses sphinx-apidoc. More on this below.

As stated above, sphinx-nested-apidoc uses sphinx-apidoc internally. This means, you can configure sphinx-apidoc from sphinx-nested-apidoc. For example:

# You can pass arguments like this:
sphinx-nested-apidoc -o docs/ mymodule/ -- -M -F --ext-githubpages
# or you can simply omit the '--'.

Everything after the required positional argument of sphinx-nested-apidoc is passed to sphinx-apidoc.

What it does not do

  • It does not modify the contents of the file. It just renames (or moves) them.

  • It is not a standalone tool. It requires sphinx-apidoc for its work.

License

MIT

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_nested_apidoc-1.2.3.tar.gz (11.5 kB view hashes)

Uploaded Source

Built Distribution

sphinx_nested_apidoc-1.2.3-py3-none-any.whl (11.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page