Sphinx extension to auto-generate API tree.
Project description
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
- Do not require
- 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
andapitree
, it also document:- Type annotations (
Union[]
, ...) - Attributes
- Type annotations (
- ...
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
- https://github.com/google-research/visu3d (https://visu3d.readthedocs.io/)
- https://github.com/google-research/dataclass_array (https://dataclass-array.readthedocs.io/)
- https://github.com/google-research/etils (https://etils.readthedocs.io/)
- https://github.com/google-research/kauldron (https://kauldron.readthedocs.io/)
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
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
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | b411cfd8091e0b193dda3197c78f846583d0eb1e41787c6b36bcf919bc544175 |
|
MD5 | 03620d0c5d0a8e36d5167685e9a92257 |
|
BLAKE2b-256 | 0a697b91bd607b86a763297cbb8a64631b7cadea161d217058701cdf07585d4c |
File details
Details for the file sphinx_apitree-1.5.3-py3-none-any.whl
.
File metadata
- Download URL: sphinx_apitree-1.5.3-py3-none-any.whl
- Upload date:
- Size: 24.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.10.12
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8809a0a66ccb701582ca8b39125057d022b538d16b5017f02c4469e5e72f48a9 |
|
MD5 | ebc222047df971e96e8547dfdced8d6e |
|
BLAKE2b-256 | 1a45d2f2745b8514ba02173ee1e1351c0625c5e262cf1b14f46d20a0542ed962 |