Added Filter and render README from template

.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

.gitignore

@@ -1,5 +1,6 @@
 .vscode
 docs/public/
+examples/*.md
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.pre-commit-config.yaml

@@ -1,3 +1,8 @@
+default_stages:
+  - pre-commit
+default_install_hook_types:
+  - pre-commit
+  - pre-push
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -11,7 +16,7 @@ repos:
     hooks:
       - id: add-trailing-comma
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.4.3
+    rev: v2.5.0
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/tox-dev/tox-ini-fmt
@@ -41,11 +46,19 @@ repos:
       - id: poetry-check
       - id: poetry-lock
   - repo: https://github.com/google/yamlfmt
-    rev: v0.13.0
+    rev: v0.14.0
     hooks:
       - id: yamlfmt
   - repo: https://github.com/PyCQA/flake8
     rev: 7.1.1
     hooks:
       - id: flake8
         args: ["--max-line-length", "88"]
+  - repo: local
+    hooks:
+      - id: readme
+        name: rendering readme
+        entry: poetry run python docs/readme.py
+        pass_filenames: false
+        always_run: true
+        language: system

.pre-commit-sample.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/d-chris/jinja2_pdoc/
+    rev: v1.1.0
+    hooks:
+      - id: jinja2pdoc
+        files: docs/.*\.jinja2$

README.md

@@ -33,33 +33,32 @@ from jinja2_pdoc import Environment
 
 env = Environment()
 
-s = """
-    # jinja2-pdoc
+template = """\
+# jinja2-pdoc
 
-    embedd python code directly from pathlib using a jinja2 extension based on pdoc
+embedd python code directly from pathlib using a jinja2 extension based on pdoc
 
-    ## docstring from pathlib.Path
+## docstring from pathlib.Path
 
-    {% pdoc pathlib:Path:docstring %}
+{% pdoc pathlib:Path:docstring %}
 
-    ## source from pathlib.Path.open
+## source from pathlib.Path.open
 
-    ```python
-    {% pdoc pathlib:Path.open:source.indent -%}
-    ```
-    """
+```python
+{% pdoc pathlib:Path.open:source.indent -%}
+```
+"""
 
-code = env.from_string(textwrap.dedent(s)).render()
+code = env.from_string(template).render()
 
-Path("example.md").write_text(code)
+print(code)
 ````
 
 ### Markdown
 
 output of the [python code](#python) above.
 
 ````markdown
-
 # jinja2-pdoc
 
 embedd python code directly from pathlib using a jinja2 extension based on pdoc
@@ -149,50 +148,77 @@ Example:
 {% pdoc pathlib:Path.open:code.dedent %}
 ```
 
-## Command Line Interface
+## Filter
 
-```console
->>> jinja2pdoc --help
-
-Usage: jinja2pdoc [OPTIONS] [FILES]...
-
-  Render jinja2 one or multiple template files, wildcards in filenames are
-  allowed, e.g. `examples/*.jinja2`.
-
-  If no 'filename' is provided in the frontmatter section of your file, e.g.
-  '<!--filename: example.md-->'. All files are written to `output` directory
-  and `suffixes` will be removed.
-
-  To ignore the frontmatter section use the `--no-meta` flag.
-
-Options:
-  -o, --output PATH             output directory for files, if no 'filename'
-                                is provided in the frontmatter.  [default:
-                                cwd]
-  -e, --encoding TEXT           encoding of the files  [default: utf-8]
-  -s, --suffixes TEXT           suffixes which will be removed from templates,
-                                if no 'filename' is provided in the
-                                frontmatter  [default: .jinja2, .j2]
-  --fail-fast                   exit on first error when rendering multiple
-                                file
-  --meta / --no-meta            parse frontmatter from the template, to search
-                                for 'filename'  [default: meta]
-  --rerender / --no-rerender    Each file is rendered only once.  [default:
-                                no-rerender]
-  --silent                      suppress console output
-  --load-path / --no-load-path  add the current working directory to path
-                                [default: load-path]
-  --help                        Show this message and exit.
+Filter to use in `jinja2` template.
+
+### include
+
+`Environment.include` - returns the content of the file.
+
+```jinja
+{{ "path/to/file" | include(enc="utf-8") }}
 ```
 
-```console
->>> jinja2pdoc .\examples\*.jinja2
-rendered         examples\example.md.jinja2......................   .\example.md
+### shell
+
+`Environment.shell` - run shell command and return the selected result from `subprocess.CompletedProcess`.
+
+```jinja
+{{ "python --version" | shell(promt=">>> %s\n") }}
 ```
 
-## pre-commit hook
+### strip
 
-**Per default the hook is not registered to `files`!**
+`Environment.strip` - remove leading and trailing whitespace and newlines from a string.
+
+```jinja
+{{ "path/to/file" | include | strip }}
+```
+
+## Command Line Interface
+
+```cmd
+$ jinja2pdoc --help
+
+  Usage: jinja2pdoc [OPTIONS] [FILES]...
+
+    Render jinja2 one or multiple template files, wildcards in filenames are
+    allowed, e.g. `examples/*.jinja2`.
+
+    If no 'filename' is provided in the frontmatter section of your file, e.g.
+    '<!--filename: example.md-->'. All files are written to `output` directory
+    and `suffixes` will be removed.
+
+    To ignore the frontmatter section use the `--no-meta` flag.
+
+  Options:
+    -o, --output PATH             output directory for files, if no 'filename'
+                                  is provided in the frontmatter.  [default:
+                                  cwd]
+    -e, --encoding TEXT           encoding of the files  [default: utf-8]
+    -s, --suffixes TEXT           suffixes which will be removed from templates,
+                                  if no 'filename' is provided in the
+                                  frontmatter  [default: .jinja2, .j2]
+    --fail-fast                   exit on first error when rendering multiple
+                                  file
+    --meta / --no-meta            parse frontmatter from the template, to search
+                                  for 'filename'  [default: meta]
+    --rerender / --no-rerender    Each file is rendered only once.  [default:
+                                  no-rerender]
+    --silent                      suppress console output
+    --load-path / --no-load-path  add the current working directory to path
+                                  [default: load-path]
+    --help                        Show this message and exit.
+```
+
+```cmd
+$ jinja2pdoc .\examples\*.jinja2
+
+  rendering        examples\example.md.jinja2......................   examples\example.md
+```
+
+## pre-commit-config
 
 To render all template files from `docs` using `.pre-commit-config.yaml` add the following.
 
@@ -207,18 +233,22 @@ repos:
         files: docs/.*\.jinja2$
 ```
 
-Use `additional_dependencies` to add extra dependencies to the pre-commit environment. Example see below.
+Use [`additional_dependencies`](https://pre-commit.com/#config-additional_dependencies) to add extra dependencies to the pre-commit environment.
 
 > This is necessary when a module or source code rendered into your template contains modules that are not part of the standard library.
 
+## pre-commit-hooks
+
+**Per default the hook is not registered to `files`!**
+
 ```yaml
-repos:
-  - repo: https://github.com/d-chris/jinja2_pdoc/
-    rev: v1.1.0
-    hooks:
-      - id: jinja2pdoc
-        files: docs/.*\.jinja2$
-        additional_dependencies: [pathlibutil]
+- id: jinja2pdoc
+  name: render jinja2pdoc
+  description: render jinja2 templates to embedd python code directly from module using pdoc.
+  entry: jinja2pdoc
+  language: python
+  types: [jinja]
+  files: ^$
 ```
 
 ## Dependencies

docs/README.md.jinja2

@@ -0,0 +1,91 @@
+# jinja2-pdoc
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/jinja2_pdoc)](https://pypi.org/project/jinja2_pdoc/)
+[![PyPI - jinja2_pdoc](https://img.shields.io/pypi/v/jinja2_pdoc)](https://pypi.org/project/jinja2_pdoc/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/jinja2_pdoc)](https://pypi.org/project/jinja2_pdoc/)
+[![PyPI - License](https://img.shields.io/pypi/l/jinja2_pdoc)](https://raw.githubusercontent.com/d-chris/jinja2_pdoc/main/LICENSE)
+[![GitHub - pytest](https://img.shields.io/github/actions/workflow/status/d-chris/jinja2_pdoc/pytest.yml?logo=github&label=pytest)](https://github.com/d-chris/jinja2_pdoc/actions/workflows/pytest.yml)
+[![GitHub - Page](https://img.shields.io/website?url=https%3A%2F%2Fd-chris.github.io%2Fjinja2_pdoc%2F&up_message=pdoc&logo=github&label=documentation)](https://d-chris.github.io/jinja2_pdoc)
+[![GitHub tag (with filter)](https://img.shields.io/github/v/tag/d-chris/jinja2_pdoc?logo=github&label=github)](https://github.com/d-chris/jinja2_pdoc)
+[![codecov](https://codecov.io/gh/d-chris/jinja2_pdoc/graph/badge.svg?token=19YB50ZL63)](https://codecov.io/gh/d-chris/jinja2_pdoc)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+
+---
+
+[`jinja2`](https://www.pypi.org/project/jinja2) extension based on [`pdoc`](https://pypi.org/project/pdoc/) to embedd python code directly from modules or files into your `jinja` template.
+
+Lazy loading of `docstrings`, `code` and `functions` directly from python modules into your `jinja2 template`.
+
+## Installation
+
+```cmd
+pip install jinja2_pdoc
+```
+
+## Example
+
+Create a markdown file with `docstrings` and `source code` from `pathlib.Path` using `jinja2` with `jinja2_pdoc` extension.
+
+### Python
+
+````python
+{{ "examples/example.py" | include }}
+````
+
+### Markdown
+
+output of the [python code](#python) above.
+
+````markdown
+{{ "python examples/example.py" | shell }}
+````
+
+## Syntax
+
+{{ "docs/syntax.md" | include }}
+
+## Filter
+
+{{ "docs/filter.md" | include }}
+
+## Command Line Interface
+
+```cmd
+{{ "jinja2pdoc --help" | shell(promt="$ ") | indent(2) }}
+```
+
+```cmd
+{{ "jinja2pdoc .\examples\*.jinja2" | shell(promt="$ ") | indent(2) }}
+```
+
+## pre-commit-config
+
+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.
+
+```yaml
+{{ ".pre-commit-sample.yaml" | include }}
+```
+
+Use [`additional_dependencies`](https://pre-commit.com/#config-additional_dependencies) to add extra dependencies to the pre-commit environment.
+
+> This is necessary when a module or source code rendered into your template contains modules that are not part of the standard library.
+
+## pre-commit-hooks
+
+**Per default the hook is not registered to `files`!**
+
+```yaml
+{{ ".pre-commit-hooks.yaml" | include }}
+```
+
+## Dependencies
+
+[![PyPI - autopep8](https://img.shields.io/pypi/v/autopep8?logo=pypi&logoColor=white&label=autopep8)](https://pypi.org/project/autopep8/)
+[![PyPI - click](https://img.shields.io/pypi/v/click?logo=pypi&logoColor=white&label=click)](https://pypi.org/project/click/)
+[![PyPI - jinja2](https://img.shields.io/pypi/v/jinja2?logo=jinja&logoColor=white&label=jinja2)](https://pypi.org/project/jinja2/)
+[![PyPI - pdoc](https://img.shields.io/pypi/v/pdoc?logo=pypi&logoColor=white&label=pdoc)](https://pypi.org/project/pdoc/)
+[![Pypi - PyYAML](https://img.shields.io/pypi/v/PyYAML?logo=pypi&logoColor=white&label=PyYAML)](https://pypi.org/project/PyYAML/)
+
+---

docs/__init__.py

@@ -0,0 +1,7 @@
+from .documentation import main as documentation
+from .readme import main as readme
+
+__all__ = [
+    "documentation",
+    "readme",
+]