sphinx-nested-apidoc: When flattened is not enough
Project description
sphinx-nested-apidoc
When flattened is not enough.
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.
Usage Overview
Let's say we have the following directory structure of our package:
mymodule/
├── fruits/
│ ├── __init__.py
│ ├── apple.py
│ ├── pear.py
│ ├── guava.py
│ └── mango.py
├── animals/
│ ├── special/
│ │ ├── __init__.py
│ │ ├── doggo.py
│ │ └── catto.py
│ ├── __init__.py
│ ├── bear.py
│ ├── giraffe.py
│ ├── monke.py
│ └── chimp.py
├── __init__.py
├── base.py
├── exceptions.py
└── secret.py
And we want to generate documentation for this package in some directory docs/
.
A short comparison
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.bear.rst
├── mymodule.animals.chimp.rst
├── mymodule.animals.giraffe.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.apple.rst
├── mymodule.fruits.guava.rst
├── mymodule.fruits.mango.rst
├── mymodule.fruits.pear.rst
├── mymodule.fruits.rst
├── mymodule.rst
└── mymodule.secret.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/
├── animals/
│ ├── bear.rst
│ ├── chimp.rst
│ ├── giraffe.rst
│ ├── index.rst
│ ├── monke.rst
│ └── special
│ ├── catto.rst
│ ├── doggo.rst
│ └── index.rst
├── fruits/
│ ├── apple.rst
│ ├── guava.rst
│ ├── index.rst
│ ├── mango.rst
│ └── pear.rst
├── index.rst
├── base.rst
├── exceptions.rst
├── modules.rst
├── mymodule.rst
└── secret.rst
Looks clean!
Usage Details
usage: sphinx-nested-apidoc [-h] [-v | -q] [--version] -o DESTDIR
module_path ...
sphinx-nested-apidoc: When flattened is not enough. sphinx-nested-apidoc is a
command-line tool which generates nested directory from sphinx-apidoc's
flattened rst 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.
sphinx_commands Commands and flags to supply to sphinx-apidoc.
optional arguments:
-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.
-q, --quiet Disable logging. This option cannot be used when
-v/--verbose is used.
--version show program's version number and exit
-o DESTDIR, --output-dir DESTDIR
directory to place all output
sphinx-nested-apidoc is licensed under MIT license. Visit
<https://github.com/arunanshub/sphinx-nested-apidoc> for more info.
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx-nested-apidoc-0.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d67dd3786863d3aa5a9220029b5541c06871cdfb6cf17ad27a8194a88c2eb127 |
|
MD5 | 03bd3ff608804380ad48888728c4ad11 |
|
BLAKE2b-256 | 19403559b1c0296b4bda9c84e962771ba43d656db24aac004e2a7f9ec86b5abb |
Hashes for sphinx_nested_apidoc-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4c23230758c94a17881a9ac44afed904281fd48cd283763be7580f5780960d52 |
|
MD5 | 99decd6f7f9514487a671ec62aaf66b7 |
|
BLAKE2b-256 | a2809ed8f33a1c89244759abf418db12457937ded8ff713e926f0d439b8be37e |