add collapse, docs and fix gettext (#2)

Author: aksiome

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4

.github/workflows/workflow.yml

@@ -13,4 +13,4 @@ jobs:
         - uses: actions/checkout@v4
         - uses: pdm-project/setup-pdm@v4
         - name: Publish package distributions to PyPI
-          run: pdm publish
+          run: pdm publish

.gitignore

@@ -1,7 +1,6 @@
-sphinx_treeview/_static/tree.css
 __pycache__
 .pdm-build
-sphinx_treeview/_static/tree.css
 .pdm-python
 .venv/
-dist/
+/build
+/dist

README.md

@@ -1,77 +1,45 @@
 # 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.
+<!-- start-include-here -->
+
+A lightweight Sphinx extension that provides a customizable, filesystem-like tree view for your documentation.
 
 ## Installation
 
+Install the extension via PyPI:
+
 ```sh
 pip install sphinx-treeview
 ```
 
-## Basic Usage
-
-Add the extension to your Sphinx `conf.py`:
+Then, add it to the `extensions` list in your `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
-:::
+extensions = ["sphinx_treeview"]
 ```
 
-The rendered tree view will look like this:
-
-![Tree View](https://raw.githubusercontent.com/Altearn/Sphinx-Tree-View/main/imgs/example.png)
-
-## Configuration Options
-
-The following options can be configured in your `conf.py`:
+If you are using [MyST Parser](https://github.com/executablebooks/myst-parser) to write Markdown documentation, it’s recommended to enable the `colon_fence` syntax extension:
 
 ```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
+extensions = ["myst_parser", "sphinx_treeview"]
+myst_enable_extensions = ["colon_fence"]
 ```
 
-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.
+<!-- end-include-here -->
 
-If you want to load all images of a folder as icons, you can use the `imagesToDecoratorIcons` function:
+## Example
 
-```python
-icons = imagesToDecoratorIcons(path="path/to/folder", sphinx_static_path="path/to/sphinx/folder")
-```
+![Example Image](https://raw.githubusercontent.com/Altearn/Sphinx-Tree-View/main/docs/_static/example.png)
 
-By default, the dimensions of the icons are 1.3em × 1.3em.
+```md
+:::{treeview}
+- {dir}`folder` folder
+  - {dir}`file` file.jpeg
+  - {dir}`file` file.png
+:::
+```
 
 # 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/).
+Images came from [pictogrammers](https://pictogrammers.com/library/mdi/) and are under [Apache-2.0 License](https://pictogrammers.com/docs/general/license/).

imgs/example.png docs/_static/example.pngimgs/example.png renamed to docs/_static/example.png

@@ -0,0 +1,42 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Sphinx Tree View"
+copyright = "2025, Altearn"
+author = "Aksiome & theogiraudet"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+extensions = [
+    "sphinx.ext.extlinks",
+    "sphinx.ext.viewcode",
+    "sphinx_inline_tabs",
+    "sphinx_treeview",
+    "myst_parser",
+]
+templates_path = ["_templates"]
+
+# -- Options for extlinks ----------------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html
+
+extlinks = {
+    "pypi": ("https://pypi.org/project/%s/", ""),
+}
+
+# -- Options for Markdown files ----------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html
+
+myst_admonition_enable = True
+myst_deflist_enable = True
+myst_heading_anchors = 3
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_title = project

docs/conf.py

@@ -0,0 +1,70 @@
+# Configuration
+
+This page describes the available configuration options for customizing the behavior and appearance of the tree view.
+
+---
+
+## Custom Icons
+
+The following options can be configured in your `conf.py`:
+
+```python
+from sphinx_treeview.decorator import DecoratorType, DecoratorIcon
+
+# Disable default decorators (e.g., the dir decorator)
+stv_disable_default_decorators = False
+
+# Add custom decorators
+stv_decorators = [
+    DecoratorType(
+        name="custom",
+        icons=[
+            DecoratorIcon(
+                path="path/to/icon.svg",
+                width=None,
+                height=None,
+                css_properties={...},
+            )
+        ]
+    )
+]
+```
+
+```{important}
+In your documentation, decorators are referenced by roles, for example: ``{dir}`folder` ...``.
+The icon name used in the tree view corresponds to the icon file’s name **without** its extension.
+```
+
+- The optional `width` and `height` parameters define the icon’s size. They accept either:
+  - A **valid CSS size string** (e.g., `16px`, `1.5em`)
+  - A **number**, interpreted as `em` units (e.g., `1.3` → `1.3em`)
+- The optional `css_properties` dictionary allows adding custom CSS styles to the icon.
+
+While `width`, `height`, and `css_properties` are available for convenience, **using CSS is generally recommended** for advanced styling. See the [Custom Styles](#custom-styles) section.
+
+To load all images from a folder as icons, use the `images_to_decorator_icons` helper:
+
+```python
+from sphinx_treeview.decorator import images_to_decorator_icons
+
+icons = images_to_decorator_icons(path="path/to/folder")
+```
+
+---
+
+## Custom Styles
+
+This extension exposes the following CSS variables for customizing the tree view’s appearance:
+
+```css
+:root {
+  --treeview-indent: 1.5rem;
+  --treeview-spacing: 0.2rem;
+  --treeview-icon-width: 1.3em;
+  --treeview-icon-height: 1.3em;
+  --treeview-color: oklch(0.5 0 0);
+  --treeview-thickness: 1px;
+}
+```
+
+Adjust these variables in your custom stylesheet to control indentation, icon sizing, colors, and line thickness.

docs/config.md

@@ -0,0 +1,40 @@
+# Sphinx Tree View
+
+```{include} ../README.md
+:start-after: <!-- start-include-here -->
+:end-before: <!-- end-include-here -->
+```
+
+## Examples
+
+A basic tree structure with one folder and two files:
+
+:::{treeview}
+- {dir}`folder` folder
+  - {dir}`file` file.jpeg
+  - {dir}`file` file.png
+:::
+
+A collapsible tree with nested folders, one collapsed by default:
+
+:::{treeview}
+- [-] {dir}`folder` folder
+  - [+] {dir}`folder` user
+    - {dir}`file` notes.txt
+  - [-] {dir}`folder` not-a-secret
+    - {dir}`file` secret.txt
+:::
+
+
+```{toctree}
+:hidden:
+usage
+config
+```
+
+```{toctree}
+:caption: Useful Links
+:hidden:
+PyPI page <https://pypi.org/project/sphinx-treeview>
+GitHub Repository <https://github.com/Altearn/Sphinx-Tree-View>
+```

docs/index.md

@@ -0,0 +1,95 @@
+# Quickstart
+
+A tree view can have an associated *decorator type*, which is used to add custom icons to the tree.
+By default, this extension provides a `dir` decorator type with basic `file` and `folder` icons.
+
+
+---
+
+## Basic Syntax
+
+Use the `treeview` directive to display interactive file or folder trees in your documentation.
+
+```{eval-rst}
+.. treeview::
+  - :dir:`folder` My Folder
+
+    - :dir:`file` image.png
+    - :dir:`file` document.pdf
+```
+
+`````{tab} MyST (Colon Fence)
+  ```md
+  :::{treeview}
+  - {dir}`folder` My Folder
+    - {dir}`file` image.png
+    - {dir}`file` document.pdf
+  :::
+  ```
+`````
+`````{tab} MyST (Directive Fence)
+  ````md
+  ```{treeview}
+  - {dir}`folder` My Folder
+    - {dir}`file` image.png
+    - {dir}`file` document.pdf
+  ```
+`````
+`````{tab} RST
+  ```rst
+  .. treeview::
+    - :dir:`folder` My Folder
+
+      - :dir:`file` image.png
+      - :dir:`file` document.pdf
+  ```
+`````
+
+---
+
+## Custom Icons
+
+The `dir` decorator provides the default `folder` and `file` icons.
+To add more icons, define **custom decorators** in your configuration.
+For setup instructions, see the [Configuration](./config.md) section.
+
+Once defined, custom decorators are used like this:
+
+```md
+:::{treeview}
+- {<decorator-type>}`<icon1>` foo
+  - {<decorator-type>}`<icon2>` bar
+- {<other-decorator>}`<icon1>` baz
+:::
+```
+
+---
+
+## Collapsible Nodes
+
+You can control whether nodes in the tree are expanded or collapsed by default using the following markers:
+
+- `[-]`: Collapsed by default
+- `[+]`: Expanded by default
+
+```{warning}
+Collapse markers should only be used on list items **that contain nested lists**.
+If used on items without children, the indicator will be ignored or may produce warnings.
+```
+
+:::{treeview}
+- [+] {dir}`folder` Open Folder
+  - {dir}`file` document.pdf
+- [-] {dir}`folder` Collapsed Folder
+  - {dir}`file` secret.txt
+:::
+
+
+```md
+:::{treeview}
+- [+] {dir}`folder` Open Folder
+  - {dir}`file` document.pdf
+- [-] {dir}`folder` Collapsed Folder
+  - {dir}`file` secret.txt
+:::
+```