Skip to content

Commit efa4c82

Browse files
d-chrisd-chris
authored
Merge pull request #15 from d-chris/develop
Added Filter and render README from template
2 parents 8e0baca + 0662251 commit efa4c82

21 files changed

+781
-188
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ jobs:
1212
- name: Set up Python
1313
uses: actions/setup-python@v5
1414
with:
15-
python-version: 3.12
15+
python-version: 3.13
1616
- name: Install dependencies
1717
run: |
18-
poetry install --only main
18+
poetry install --only main,docs
1919
- name: Build Documentation
2020
run: |
2121
poetry run python -m docs

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
.vscode
22
docs/public/
3+
examples/*.md
34

45
# Byte-compiled / optimized / DLL files
56
__pycache__/

‎.pre-commit-config.yaml‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
default_stages:
2+
- pre-commit
3+
default_install_hook_types:
4+
- pre-commit
5+
- pre-push
16
repos:
27
- repo: https://github.com/pre-commit/pre-commit-hooks
38
rev: v5.0.0
@@ -11,7 +16,7 @@ repos:
1116
hooks:
1217
- id: add-trailing-comma
1318
- repo: https://github.com/tox-dev/pyproject-fmt
14-
rev: v2.4.3
19+
rev: v2.5.0
1520
hooks:
1621
- id: pyproject-fmt
1722
- repo: https://github.com/tox-dev/tox-ini-fmt
@@ -41,11 +46,19 @@ repos:
4146
- id: poetry-check
4247
- id: poetry-lock
4348
- repo: https://github.com/google/yamlfmt
44-
rev: v0.13.0
49+
rev: v0.14.0
4550
hooks:
4651
- id: yamlfmt
4752
- repo: https://github.com/PyCQA/flake8
4853
rev: 7.1.1
4954
hooks:
5055
- id: flake8
5156
args: ["--max-line-length", "88"]
57+
- repo: local
58+
hooks:
59+
- id: readme
60+
name: rendering readme
61+
entry: poetry run python docs/readme.py
62+
pass_filenames: false
63+
always_run: true
64+
language: system

‎.pre-commit-sample.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
repos:
2+
- repo: https://github.com/d-chris/jinja2_pdoc/
3+
rev: v1.1.0
4+
hooks:
5+
- id: jinja2pdoc
6+
files: docs/.*\.jinja2$

‎README.md‎

Lines changed: 89 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -33,33 +33,32 @@ from jinja2_pdoc import Environment
3333

3434
env = Environment()
3535

36-
s = """
37-
# jinja2-pdoc
36+
template = """\
37+
# jinja2-pdoc
3838
39-
embedd python code directly from pathlib using a jinja2 extension based on pdoc
39+
embedd python code directly from pathlib using a jinja2 extension based on pdoc
4040
41-
## docstring from pathlib.Path
41+
## docstring from pathlib.Path
4242
43-
{% pdoc pathlib:Path:docstring %}
43+
{% pdoc pathlib:Path:docstring %}
4444
45-
## source from pathlib.Path.open
45+
## source from pathlib.Path.open
4646
47-
```python
48-
{% pdoc pathlib:Path.open:source.indent -%}
49-
```
50-
"""
47+
```python
48+
{% pdoc pathlib:Path.open:source.indent -%}
49+
```
50+
"""
5151

52-
code = env.from_string(textwrap.dedent(s)).render()
52+
code = env.from_string(template).render()
5353

54-
Path("example.md").write_text(code)
54+
print(code)
5555
````
5656

5757
### Markdown
5858

5959
output of the [python code](#python) above.
6060

6161
````markdown
62-
6362
# jinja2-pdoc
6463

6564
embedd python code directly from pathlib using a jinja2 extension based on pdoc
@@ -149,50 +148,77 @@ Example:
149148
{% pdoc pathlib:Path.open:code.dedent %}
150149
```
151150

152-
## Command Line Interface
151+
## Filter
153152

154-
```console
155-
>>> jinja2pdoc --help
156-
157-
Usage: jinja2pdoc [OPTIONS] [FILES]...
158-
159-
Render jinja2 one or multiple template files, wildcards in filenames are
160-
allowed, e.g. `examples/*.jinja2`.
161-
162-
If no 'filename' is provided in the frontmatter section of your file, e.g.
163-
'<!--filename: example.md-->'. All files are written to `output` directory
164-
and `suffixes` will be removed.
165-
166-
To ignore the frontmatter section use the `--no-meta` flag.
167-
168-
Options:
169-
-o, --output PATH output directory for files, if no 'filename'
170-
is provided in the frontmatter. [default:
171-
cwd]
172-
-e, --encoding TEXT encoding of the files [default: utf-8]
173-
-s, --suffixes TEXT suffixes which will be removed from templates,
174-
if no 'filename' is provided in the
175-
frontmatter [default: .jinja2, .j2]
176-
--fail-fast exit on first error when rendering multiple
177-
file
178-
--meta / --no-meta parse frontmatter from the template, to search
179-
for 'filename' [default: meta]
180-
--rerender / --no-rerender Each file is rendered only once. [default:
181-
no-rerender]
182-
--silent suppress console output
183-
--load-path / --no-load-path add the current working directory to path
184-
[default: load-path]
185-
--help Show this message and exit.
153+
Filter to use in `jinja2` template.
154+
155+
### include
156+
157+
`Environment.include` - returns the content of the file.
158+
159+
```jinja
160+
{{ "path/to/file" | include(enc="utf-8") }}
186161
```
187162

188-
```console
189-
>>> jinja2pdoc .\examples\*.jinja2
190-
rendered examples\example.md.jinja2...................... .\example.md
163+
### shell
164+
165+
`Environment.shell` - run shell command and return the selected result from `subprocess.CompletedProcess`.
166+
167+
```jinja
168+
{{ "python --version" | shell(promt=">>> %s\n") }}
191169
```
192170

193-
## pre-commit hook
171+
### strip
194172

195-
**Per default the hook is not registered to `files`!**
173+
`Environment.strip` - remove leading and trailing whitespace and newlines from a string.
174+
175+
```jinja
176+
{{ "path/to/file" | include | strip }}
177+
```
178+
179+
## Command Line Interface
180+
181+
```cmd
182+
$ jinja2pdoc --help
183+
184+
Usage: jinja2pdoc [OPTIONS] [FILES]...
185+
186+
Render jinja2 one or multiple template files, wildcards in filenames are
187+
allowed, e.g. `examples/*.jinja2`.
188+
189+
If no 'filename' is provided in the frontmatter section of your file, e.g.
190+
'<!--filename: example.md-->'. All files are written to `output` directory
191+
and `suffixes` will be removed.
192+
193+
To ignore the frontmatter section use the `--no-meta` flag.
194+
195+
Options:
196+
-o, --output PATH output directory for files, if no 'filename'
197+
is provided in the frontmatter. [default:
198+
cwd]
199+
-e, --encoding TEXT encoding of the files [default: utf-8]
200+
-s, --suffixes TEXT suffixes which will be removed from templates,
201+
if no 'filename' is provided in the
202+
frontmatter [default: .jinja2, .j2]
203+
--fail-fast exit on first error when rendering multiple
204+
file
205+
--meta / --no-meta parse frontmatter from the template, to search
206+
for 'filename' [default: meta]
207+
--rerender / --no-rerender Each file is rendered only once. [default:
208+
no-rerender]
209+
--silent suppress console output
210+
--load-path / --no-load-path add the current working directory to path
211+
[default: load-path]
212+
--help Show this message and exit.
213+
```
214+
215+
```cmd
216+
$ jinja2pdoc .\examples\*.jinja2
217+
218+
rendering examples\example.md.jinja2...................... examples\example.md
219+
```
220+
221+
## pre-commit-config
196222

197223
To render all template files from `docs` using `.pre-commit-config.yaml` add the following.
198224

@@ -207,18 +233,22 @@ repos:
207233
files: docs/.*\.jinja2$
208234
```
209235
210-
Use `additional_dependencies` to add extra dependencies to the pre-commit environment. Example see below.
236+
Use [`additional_dependencies`](https://pre-commit.com/#config-additional_dependencies) to add extra dependencies to the pre-commit environment.
211237

212238
> This is necessary when a module or source code rendered into your template contains modules that are not part of the standard library.
213239

240+
## pre-commit-hooks
241+
242+
**Per default the hook is not registered to `files`!**
243+
214244
```yaml
215-
repos:
216-
- repo: https://github.com/d-chris/jinja2_pdoc/
217-
rev: v1.1.0
218-
hooks:
219-
- id: jinja2pdoc
220-
files: docs/.*\.jinja2$
221-
additional_dependencies: [pathlibutil]
245+
- id: jinja2pdoc
246+
name: render jinja2pdoc
247+
description: render jinja2 templates to embedd python code directly from module using pdoc.
248+
entry: jinja2pdoc
249+
language: python
250+
types: [jinja]
251+
files: ^$
222252
```
223253

224254
## Dependencies

‎docs/README.md.jinja2‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# jinja2-pdoc
2+
3+
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/jinja2_pdoc)](https://pypi.org/project/jinja2_pdoc/)
4+
[![PyPI - jinja2_pdoc](https://img.shields.io/pypi/v/jinja2_pdoc)](https://pypi.org/project/jinja2_pdoc/)
5+
[![PyPI - Downloads](https://img.shields.io/pypi/dm/jinja2_pdoc)](https://pypi.org/project/jinja2_pdoc/)
6+
[![PyPI - License](https://img.shields.io/pypi/l/jinja2_pdoc)](https://raw.githubusercontent.com/d-chris/jinja2_pdoc/main/LICENSE)
7+
[![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)
8+
[![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)
9+
[![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)
10+
[![codecov](https://codecov.io/gh/d-chris/jinja2_pdoc/graph/badge.svg?token=19YB50ZL63)](https://codecov.io/gh/d-chris/jinja2_pdoc)
11+
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
12+
13+
---
14+
15+
[`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.
16+
17+
Lazy loading of `docstrings`, `code` and `functions` directly from python modules into your `jinja2 template`.
18+
19+
## Installation
20+
21+
```cmd
22+
pip install jinja2_pdoc
23+
```
24+
25+
## Example
26+
27+
Create a markdown file with `docstrings` and `source code` from `pathlib.Path` using `jinja2` with `jinja2_pdoc` extension.
28+
29+
### Python
30+
31+
````python
32+
{{ "examples/example.py" | include }}
33+
````
34+
35+
### Markdown
36+
37+
output of the [python code](#python) above.
38+
39+
````markdown
40+
{{ "python examples/example.py" | shell }}
41+
````
42+
43+
## Syntax
44+
45+
{{ "docs/syntax.md" | include }}
46+
47+
## Filter
48+
49+
{{ "docs/filter.md" | include }}
50+
51+
## Command Line Interface
52+
53+
```cmd
54+
{{ "jinja2pdoc --help" | shell(promt="$ ") | indent(2) }}
55+
```
56+
57+
```cmd
58+
{{ "jinja2pdoc .\examples\*.jinja2" | shell(promt="$ ") | indent(2) }}
59+
```
60+
61+
## pre-commit-config
62+
63+
To render all template files from `docs` using `.pre-commit-config.yaml` add the following.
64+
65+
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.
66+
67+
```yaml
68+
{{ ".pre-commit-sample.yaml" | include }}
69+
```
70+
71+
Use [`additional_dependencies`](https://pre-commit.com/#config-additional_dependencies) to add extra dependencies to the pre-commit environment.
72+
73+
> This is necessary when a module or source code rendered into your template contains modules that are not part of the standard library.
74+
75+
## pre-commit-hooks
76+
77+
**Per default the hook is not registered to `files`!**
78+
79+
```yaml
80+
{{ ".pre-commit-hooks.yaml" | include }}
81+
```
82+
83+
## Dependencies
84+
85+
[![PyPI - autopep8](https://img.shields.io/pypi/v/autopep8?logo=pypi&logoColor=white&label=autopep8)](https://pypi.org/project/autopep8/)
86+
[![PyPI - click](https://img.shields.io/pypi/v/click?logo=pypi&logoColor=white&label=click)](https://pypi.org/project/click/)
87+
[![PyPI - jinja2](https://img.shields.io/pypi/v/jinja2?logo=jinja&logoColor=white&label=jinja2)](https://pypi.org/project/jinja2/)
88+
[![PyPI - pdoc](https://img.shields.io/pypi/v/pdoc?logo=pypi&logoColor=white&label=pdoc)](https://pypi.org/project/pdoc/)
89+
[![Pypi - PyYAML](https://img.shields.io/pypi/v/PyYAML?logo=pypi&logoColor=white&label=PyYAML)](https://pypi.org/project/PyYAML/)
90+
91+
---

‎docs/__init__.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
from .documentation import main as documentation
2+
from .readme import main as readme
3+
4+
__all__ = [
5+
"documentation",
6+
"readme",
7+
]

0 commit comments

Comments
 (0)