| Name | sphinx-treeview JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | Add support for tree view to Sphinx. |
| upload_time | 2024-12-21 14:02:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ==3.12.* |
| license | MPL-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
sphinx
jinja2
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Sphinx Tree View
A lightweight Sphinx extension that provides a customizable tree view for documentation.
A tree view can have an associated decorator type, which can be used to add custom icons to the tree view.
By default, the extension provides a decorator type "dir" with file and folder icons.
## Installation
```sh
pip install sphinx-treeview
```
## Basic Usage
Add the extension to your Sphinx `conf.py`:
```python
extensions = [
'sphinx_treeview'
]
```
Use the directive in your RST files:
```rst
:::{treeview}
- {<decorator name>}`<icon1>` foo
- {<decorator name>}`<icon2>` bar
- <decorator>`<icon1>` baz
:::
```
For example, with the default decorator "dir":
```rst
:::{treeview}
- {dir}`<folder>` folder
- {dir}`<file>` file.jpeg
- {dir}`<file>` file.png
:::
```
The rendered tree view will look like this:
## Configuration Options
The following options can be configured in your `conf.py`:
```python
# Add custom decorators
stv_decorators = [
DecoratorType(name="custom", icons=[DecoratorIcon(path="path/to/icon.svg", sphinx_static_path="icon/path/for/sphinx/", width=1.3, height=1.3, css_properties={...})])
]
# Disable default decorators (dir decorator)
stv_disable_default_decorators = False
```
A decorator icon is defined by a `path` to the icon file, and the path where the icon will be copied to in the Sphinx static folder.
This second path is used in the CSS to load the icon.
`width` and `height` are the dimensions of the icon in `em`, and `css_properties` is a dictionary of CSS properties to be applied to the icon.
The name used for the icon in the tree view is the name of the icon file without the extension.
If you want to load all images of a folder as icons, you can use the `imagesToDecoratorIcons` function:
```python
icons = imagesToDecoratorIcons(path="path/to/folder", sphinx_static_path="path/to/sphinx/folder")
```
By default, the dimensions of the icons are 1.3em × 1.3em.
# License
This project is licensed under the MPL-2.0 License. See the [LICENSE](LICENSE) file for details.
Images came from [pictogrammers](https://pictogrammers.com/library/mdi/) and are under [Apache-2.0 License](https://pictogrammers.com/docs/general/license/).
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-treeview",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.12.*",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "theogiraudet <theo.giraudet@altearn.xyz>, Aksiome <maxime.calmon@altearn.xyz>",
"download_url": "https://files.pythonhosted.org/packages/79/3d/3c882842459a051b3570418fc06e03100421e1982d1bae1a1d57a035b3ae/sphinx_treeview-1.0.1.tar.gz",
"platform": null,
"description": "# Sphinx Tree View\n\nA lightweight Sphinx extension that provides a customizable tree view for documentation.\nA tree view can have an associated decorator type, which can be used to add custom icons to the tree view.\nBy default, the extension provides a decorator type \"dir\" with file and folder icons.\n\n## Installation\n\n```sh\npip install sphinx-treeview\n```\n\n## Basic Usage\n\nAdd the extension to your Sphinx `conf.py`:\n\n```python\nextensions = [\n 'sphinx_treeview'\n]\n```\n\nUse the directive in your RST files:\n\n```rst\n:::{treeview}\n- {<decorator name>}`<icon1>` foo\n - {<decorator name>}`<icon2>` bar\n- <decorator>`<icon1>` baz\n:::\n```\n\nFor example, with the default decorator \"dir\":\n\n```rst\n:::{treeview}\n- {dir}`<folder>` folder\n - {dir}`<file>` file.jpeg\n - {dir}`<file>` file.png\n:::\n```\n\nThe rendered tree view will look like this:\n\n\n\n## Configuration Options\n\nThe following options can be configured in your `conf.py`:\n\n```python\n# Add custom decorators\nstv_decorators = [\n DecoratorType(name=\"custom\", icons=[DecoratorIcon(path=\"path/to/icon.svg\", sphinx_static_path=\"icon/path/for/sphinx/\", width=1.3, height=1.3, css_properties={...})])\n]\n\n# Disable default decorators (dir decorator)\nstv_disable_default_decorators = False\n```\n\nA decorator icon is defined by a `path` to the icon file, and the path where the icon will be copied to in the Sphinx static folder.\nThis second path is used in the CSS to load the icon.\n`width` and `height` are the dimensions of the icon in `em`, and `css_properties` is a dictionary of CSS properties to be applied to the icon.\nThe name used for the icon in the tree view is the name of the icon file without the extension.\n\nIf you want to load all images of a folder as icons, you can use the `imagesToDecoratorIcons` function:\n\n```python\nicons = imagesToDecoratorIcons(path=\"path/to/folder\", sphinx_static_path=\"path/to/sphinx/folder\")\n```\n\nBy default, the dimensions of the icons are 1.3em \u00d7 1.3em.\n\n# License\n\nThis project is licensed under the MPL-2.0 License. See the [LICENSE](LICENSE) file for details.\nImages came from [pictogrammers](https://pictogrammers.com/library/mdi/) and are under [Apache-2.0 License](https://pictogrammers.com/docs/general/license/).",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Add support for tree view to Sphinx.",
"version": "1.0.1",
"project_urls": {
"Issues": "https://github.com/Altearn/Sphinx-Tree-View/issues",
"Repository": "https://github.com/Altearn/Sphinx-Tree-View"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ea7126c15fd93a5d60fd99cedbcbe633578c79e94809e4f5cfb4c9186e7e1c5",
"md5": "9da3528a95c2872521760286da84a1c9",
"sha256": "7ee0b2f531fbc9b3926c0934cf1e1263b3316186556f150d3c5e6095ea83ee7d"
},
"downloads": -1,
"filename": "sphinx_treeview-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9da3528a95c2872521760286da84a1c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.12.*",
"size": 12723,
"upload_time": "2024-12-21T14:02:37",
"upload_time_iso_8601": "2024-12-21T14:02:37.494343Z",
"url": "https://files.pythonhosted.org/packages/4e/a7/126c15fd93a5d60fd99cedbcbe633578c79e94809e4f5cfb4c9186e7e1c5/sphinx_treeview-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "793d3c882842459a051b3570418fc06e03100421e1982d1bae1a1d57a035b3ae",
"md5": "b74e85bf2d9add9b9fd724508399ad1a",
"sha256": "78075d015d57d8f7d5b9c08ae309fdea871cf8eeb94a4aa5f8afe53b933d4c8a"
},
"downloads": -1,
"filename": "sphinx_treeview-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b74e85bf2d9add9b9fd724508399ad1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.12.*",
"size": 10017,
"upload_time": "2024-12-21T14:02:39",
"upload_time_iso_8601": "2024-12-21T14:02:39.606904Z",
"url": "https://files.pythonhosted.org/packages/79/3d/3c882842459a051b3570418fc06e03100421e1982d1bae1a1d57a035b3ae/sphinx_treeview-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-21 14:02:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Altearn",
"github_project": "Sphinx-Tree-View",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sphinx",
"specs": []
},
{
"name": "jinja2",
"specs": []
}
],
"lcname": "sphinx-treeview"
}
