Skip to main content

Sphinx extension to auto-generate API tree.

Project description

sphinx-apitree

Unittests PyPI version

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

  1. In pyproject.toml

    [project.optional-dependencies]
    # Installed through `pip install .[docs]`
    docs = [
        # Install `apitree` with all extensions (sphinx, theme,...)
        "sphinx-apitree[ext]",
    ]
    
  2. 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

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_apitree-1.5.3.tar.gz (19.7 kB view details)

Uploaded Source

Built Distribution

sphinx_apitree-1.5.3-py3-none-any.whl (24.8 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_apitree-1.5.3.tar.gz.

File metadata

  • Download URL: sphinx_apitree-1.5.3.tar.gz
  • Upload date:
  • Size: 19.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for sphinx_apitree-1.5.3.tar.gz
Algorithm Hash digest
SHA256 b411cfd8091e0b193dda3197c78f846583d0eb1e41787c6b36bcf919bc544175
MD5 03620d0c5d0a8e36d5167685e9a92257
BLAKE2b-256 0a697b91bd607b86a763297cbb8a64631b7cadea161d217058701cdf07585d4c

See more details on using hashes here.

File details

Details for the file sphinx_apitree-1.5.3-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_apitree-1.5.3-py3-none-any.whl
Algorithm Hash digest
SHA256 8809a0a66ccb701582ca8b39125057d022b538d16b5017f02c4469e5e72f48a9
MD5 ebc222047df971e96e8547dfdced8d6e
BLAKE2b-256 1a45d2f2745b8514ba02173ee1e1351c0625c5e262cf1b14f46d20a0542ed962

See more details on using hashes here.

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