Enhance documentation with new filter examples

Author: d-chris

.github/workflows/publish.yml

@@ -12,10 +12,10 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.12
+          python-version: 3.13
       - name: Install dependencies
         run: |
-          poetry install --only main
+          poetry install --only main,docs
       - name: Build Documentation
         run: |
           poetry run python -m docs

README.md

@@ -148,6 +148,34 @@ Example:
 {% pdoc pathlib:Path.open:code.dedent %}
 ```
 
+## Filter
+
+Filter to use in `jinja2` template.
+
+### include
+
+`Environment.include` - returns the content of the file.
+
+```jinja
+{{ "path/to/file" | include(enc="utf-8") }}
+```
+
+### shell
+
+`Environment.shell` - run shell command and return the selected result from `subprocess.CompletedProcess`.
+
+```jinja
+{{ "python --version" | shell(promt=">>> %s\n") }}
+```
+
+### strip
+
+`Environment.strip` - remove leading and trailing whitespace and newlines from a string.
+
+```jinja
+{{ "path/to/file" | include | strip }}
+```
+
 ## Command Line Interface
 
 ```cmd
@@ -192,8 +220,6 @@ $ jinja2pdoc .\examples\*.jinja2
 
 ## pre-commit-config
 
-**Per default the hook is not registered to `files`!**
-
 To render all template files from `docs` using `.pre-commit-config.yaml` add the following.
 
 You may add a `frontmatter` section at the beginning of in your templates to specify output directory and filename, e.g. `<!--filename: example.md-->`. If no metadata are at the beginning of the  template, the rendered file is written to the `output` directory which is default the current working direktory.
@@ -213,6 +239,8 @@ Use [`additional_dependencies`](https://pre-commit.com/#config-additional_depend
 
 ## pre-commit-hooks
 
+**Per default the hook is not registered to `files`!**
+
 ```yaml
 - id: jinja2pdoc
   name: render jinja2pdoc

docs/README.md.jinja2

@@ -44,6 +44,10 @@ output of the [python code](#python) above.
 
 {{ "docs/syntax.md" | include }}
 
+## Filter
+
+{{ "docs/filter.md" | include }}
+
 ## Command Line Interface
 
 ```cmd
@@ -56,8 +60,6 @@ output of the [python code](#python) above.
 
 ## pre-commit-config
 
-**Per default the hook is not registered to `files`!**
-
 To render all template files from `docs` using `.pre-commit-config.yaml` add the following.
 
 You may add a `frontmatter` section at the beginning of in your templates to specify output directory and filename, e.g. `<!--filename: example.md-->`. If no metadata are at the beginning of the  template, the rendered file is written to the `output` directory which is default the current working direktory.
@@ -72,6 +74,8 @@ Use [`additional_dependencies`](https://pre-commit.com/#config-additional_depend
 
 ## pre-commit-hooks
 
+**Per default the hook is not registered to `files`!**
+
 ```yaml
 {{ ".pre-commit-hooks.yaml" | include }}
 ```

docs/filter.md

@@ -0,0 +1,25 @@
+Filter to use in `jinja2` template.
+
+### include
+
+`Environment.include` - returns the content of the file.
+
+```jinja
+{{ "path/to/file" | include(enc="utf-8") }}
+```
+
+### shell
+
+`Environment.shell` - run shell command and return the selected result from `subprocess.CompletedProcess`.
+
+```jinja
+{{ "python --version" | shell(promt=">>> %s\n") }}
+```
+
+### strip
+
+`Environment.strip` - remove leading and trailing whitespace and newlines from a string.
+
+```jinja
+{{ "path/to/file" | include | strip }}
+```

jinja2_pdoc/environment.py

@@ -115,11 +115,9 @@ def include(
             str: The content of the file.
 
         Example:
-            ````jinja2
-            ```yaml
+            ```jinja2
             {{ ".pre-commit-hool.yaml" | include }}
             ```
-            ````
         """
 
         content = Path(file).read_text(encoding=enc)
@@ -137,9 +135,14 @@ def strip(text: str, chars: str = "\n ") -> str:
         Args:
             text (str): The text to be stripped.
             chars (str, optional): The characters to be stripped from the text.
-            Defaults to `"\n "`.
+            Defaults to `"\\n "`.
 
         Returns:
             str: The stripped text.
+
+        Example:
+            ```jinja2
+            {{ "  hello world.  \\n" | strip }}
+            ```
         """
         return text.strip(chars)