| Name | sphinx-apitree JSON |
| Version |
1.5.3
JSON |
| download |
| home_page | |
| Summary | Sphinx extension to auto-generate API tree. |
| upload_time | 2023-08-18 08:37:01 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.10 |
| license | |
| 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": "",
"name": "sphinx-apitree",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "sphinx,doc",
"author": "",
"author_email": "Conchylicultor <etiennefg.pot@mail.com>",
"download_url": "https://files.pythonhosted.org/packages/0a/69/7b91bd607b86a763297cbb8a64631b7cadea161d217058701cdf07585d4c/sphinx_apitree-1.5.3.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": "",
"summary": "Sphinx extension to auto-generate API tree.",
"version": "1.5.3",
"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": "1a45d2f2745b8514ba02173ee1e1351c0625c5e262cf1b14f46d20a0542ed962",
"md5": "ebc222047df971e96e8547dfdced8d6e",
"sha256": "8809a0a66ccb701582ca8b39125057d022b538d16b5017f02c4469e5e72f48a9"
},
"downloads": -1,
"filename": "sphinx_apitree-1.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebc222047df971e96e8547dfdced8d6e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24782,
"upload_time": "2023-08-18T08:36:59",
"upload_time_iso_8601": "2023-08-18T08:36:59.554697Z",
"url": "https://files.pythonhosted.org/packages/1a/45/d2f2745b8514ba02173ee1e1351c0625c5e262cf1b14f46d20a0542ed962/sphinx_apitree-1.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a697b91bd607b86a763297cbb8a64631b7cadea161d217058701cdf07585d4c",
"md5": "03620d0c5d0a8e36d5167685e9a92257",
"sha256": "b411cfd8091e0b193dda3197c78f846583d0eb1e41787c6b36bcf919bc544175"
},
"downloads": -1,
"filename": "sphinx_apitree-1.5.3.tar.gz",
"has_sig": false,
"md5_digest": "03620d0c5d0a8e36d5167685e9a92257",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19728,
"upload_time": "2023-08-18T08:37:01",
"upload_time_iso_8601": "2023-08-18T08:37:01.474282Z",
"url": "https://files.pythonhosted.org/packages/0a/69/7b91bd607b86a763297cbb8a64631b7cadea161d217058701cdf07585d4c/sphinx_apitree-1.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-18 08:37:01",
"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"
}
