sphinx-apitree

apitree is a small library to generate a ready-to-use documentation with minimal friction!

apitree takes care of everything, so you can only focus on the code.

Usage

In docs/conf.py, replace everything by:

import apitree

apitree.make_project(
    # e.g. `import visu3d as v3d` -> {'v3d': 'visu3d'}
    project_name={'alias': 'my_module'},
    globals=globals(),
)

Then to generate the doc:

sphinx-build -b html docs/ docs/_build

To add api/my_module/index somewhere in your toctree, like:

..toctree:
  :caption: API

  api/my_module/index

Features

All included: Single function call include the theme, the API generation,...
Auto-generate the API tree:
- Do not require __all__ (smart detect of which symbols are documented)
- Add expandable toc tree with all symbols
Add links to GitHub.
Markdown (.md) / Jupyter (.ipynb) support out of the box
Auto-cross-references (Just annotate markdown inline-code my_symbol and links are auto-added)
Contrary to autodoc and apitree, it also document:
- Type annotations (Union[], ...)
- Attributes
...

Installation in a project

In pyproject.toml

[project.optional-dependencies]
# Installed through `pip install .[docs]`
docs = [
    # Install `apitree` with all extensions (sphinx, theme,...)
    "sphinx-apitree[ext]",
]

In .readthedocs.yaml

sphinx:
configuration: docs/conf.py

python:
install:
    - method: pip
    path: .
    extra_requirements:
        - docs

Options

By default, apitree tries to infer everything automatically. However there's sometimes times where the user want to overwrite the default choices.

Package vs module: By default, all __init__.py define the public API (imports documented), while the modules (module.py) define the implementation (imports not documented). You can explicitly mark a module as package, so it's import are documented, by adding in the module definition:
```
__apitree__ = dict(
    is_package=True,
)
```

Examples of projects using apitree

Generated with:

echo start \
&& cd ../visu3d          && sphinx-build -b html docs/ docs/_build \
&& cd ../dataclass_array && sphinx-build -b html docs/ docs/_build \
&& cd ../etils           && sphinx-build -b html docs/ docs/_build \
&& cd ../kauldron        && sphinx-build -b html docs/ docs/_build \
&& echo finished

Oven

sphinx-apitree1.6.0

Package Downloads

Authors

Project URLs

Requires Python

Dependencies