| Name | sphinx-apitree JSON |
| Version |
1.6.0
JSON |
| download |
| home_page | None |
| Summary | Sphinx extension to auto-generate API tree. |
| upload_time | 2024-11-27 15:03:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
sphinx
doc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinx-apitree
[](https://github.com/conchylicultor/sphinx-apitree/actions/workflows/pytest_and_autopublish.yml)
[](https://badge.fury.io/py/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:
```python
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:
```sh
sphinx-build -b html docs/ docs/_build
```
To add `api/my_module/index` somewhere in your toctree, like:
```md
..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`
```toml
[project.optional-dependencies]
# Installed through `pip install .[docs]`
docs = [
# Install `apitree` with all extensions (sphinx, theme,...)
"sphinx-apitree[ext]",
]
```
1. In `.readthedocs.yaml`
```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:
```python
__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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-apitree",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "sphinx, doc",
"author": null,
"author_email": "Conchylicultor <etiennefg.pot@mail.com>",
"download_url": "https://files.pythonhosted.org/packages/e1/ad/887933971d5bcc9e3b0bc284b72197bd1721da32c14624f5156ff6d7ac47/sphinx_apitree-1.6.0.tar.gz",
"platform": null,
"description": "# sphinx-apitree\n\n[](https://github.com/conchylicultor/sphinx-apitree/actions/workflows/pytest_and_autopublish.yml)\n[](https://badge.fury.io/py/sphinx-apitree)\n\n\n`apitree` is a small library to generate a ready-to-use documentation with minimal friction!\n\n`apitree` takes care of everything, so you can only focus on the code.\n\n## Usage\n\nIn `docs/conf.py`, replace everything by:\n\n```python\nimport apitree\n\napitree.make_project(\n # e.g. `import visu3d as v3d` -> {'v3d': 'visu3d'}\n project_name={'alias': 'my_module'},\n globals=globals(),\n)\n```\n\nThen to generate the doc:\n\n```sh\nsphinx-build -b html docs/ docs/_build\n```\n\nTo add `api/my_module/index` somewhere in your toctree, like:\n\n```md\n..toctree:\n :caption: API\n\n api/my_module/index\n```\n\n## Features\n\n* All included: Single function call include the theme, the API generation,...\n* Auto-generate the API tree:\n * Do not require `__all__` (smart detect of which symbols are documented)\n * Add expandable toc tree with all symbols\n* Add links to `GitHub`.\n* Markdown (`.md`) / Jupyter (`.ipynb`) support out of the box\n* Auto-cross-references (Just annotate markdown inline-code `my_symbol` and links are auto-added)\n* Contrary to `autodoc` and `apitree`, it also document:\n * Type annotations (`Union[]`, ...)\n * Attributes\n* ...\n\n## Installation in a project\n\n1. In `pyproject.toml`\n\n ```toml\n [project.optional-dependencies]\n # Installed through `pip install .[docs]`\n docs = [\n # Install `apitree` with all extensions (sphinx, theme,...)\n \"sphinx-apitree[ext]\",\n ]\n ```\n\n1. In `.readthedocs.yaml`\n\n ```yaml\n sphinx:\n configuration: docs/conf.py\n\n python:\n install:\n - method: pip\n path: .\n extra_requirements:\n - docs\n ```\n\n## Options\n\nBy default, `apitree` tries to infer everything automatically. However there's sometimes\ntimes where the user want to overwrite the default choices.\n\n* Package vs module: By default, all `__init__.py` define the public API (imports documented), while\n the modules (`module.py`) define the implementation (imports not documented).\n You can explicitly mark a module as package, so it's import are documented, by adding in the\n module definition:\n\n ```python\n __apitree__ = dict(\n is_package=True,\n )\n ```\n\n## Examples of projects using apitree\n\n* https://github.com/google-research/visu3d (https://visu3d.readthedocs.io/)\n* https://github.com/google-research/dataclass_array (https://dataclass-array.readthedocs.io/)\n* https://github.com/google-research/etils (https://etils.readthedocs.io/)\n* https://github.com/google-research/kauldron (https://kauldron.readthedocs.io/)\n\nGenerated with:\n\n```\necho start \\\n&& cd ../visu3d && sphinx-build -b html docs/ docs/_build \\\n&& cd ../dataclass_array && sphinx-build -b html docs/ docs/_build \\\n&& cd ../etils && sphinx-build -b html docs/ docs/_build \\\n&& cd ../kauldron && sphinx-build -b html docs/ docs/_build \\\n&& echo finished\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Sphinx extension to auto-generate API tree.",
"version": "1.6.0",
"project_urls": {
"homepage": "https://github.com/conchylicultor/sphinx-apitree",
"repository": "https://github.com/conchylicultor/sphinx-apitree"
},
"split_keywords": [
"sphinx",
" doc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "235d2b7fa1e16e8a7c8edbe40f5bee9d5532b2e2e70850b6ab31e682b93bcc04",
"md5": "e1b965b33e4b0f5806cf9a83ae683d91",
"sha256": "bbf8d8808a08093845079620fdf6cf23e9836b8a25cee0ca69a04e352c4b5a25"
},
"downloads": -1,
"filename": "sphinx_apitree-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1b965b33e4b0f5806cf9a83ae683d91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25217,
"upload_time": "2024-11-27T15:03:09",
"upload_time_iso_8601": "2024-11-27T15:03:09.562272Z",
"url": "https://files.pythonhosted.org/packages/23/5d/2b7fa1e16e8a7c8edbe40f5bee9d5532b2e2e70850b6ab31e682b93bcc04/sphinx_apitree-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1ad887933971d5bcc9e3b0bc284b72197bd1721da32c14624f5156ff6d7ac47",
"md5": "4bb482b0379860e67d3d82f24811b8ca",
"sha256": "68021fc57f36e7b18af14bb861278daaf7f64926a6d86ee459409a962b8585ae"
},
"downloads": -1,
"filename": "sphinx_apitree-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "4bb482b0379860e67d3d82f24811b8ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 20121,
"upload_time": "2024-11-27T15:03:11",
"upload_time_iso_8601": "2024-11-27T15:03:11.244638Z",
"url": "https://files.pythonhosted.org/packages/e1/ad/887933971d5bcc9e3b0bc284b72197bd1721da32c14624f5156ff6d7ac47/sphinx_apitree-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-27 15:03:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "conchylicultor",
"github_project": "sphinx-apitree",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-apitree"
}
