# jinja2-pdoc
[](https://pypi.org/project/jinja2_pdoc/)
[](https://pypi.org/project/jinja2_pdoc/)
[](https://pypi.org/project/jinja2_pdoc/)
[](https://raw.githubusercontent.com/d-chris/jinja2_pdoc/main/LICENSE)
[](https://github.com/d-chris/jinja2_pdoc/actions/workflows/pytest.yml)
[](https://d-chris.github.io/jinja2_pdoc)
[](https://github.com/d-chris/jinja2_pdoc)
[](https://codecov.io/gh/d-chris/jinja2_pdoc)
[](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
from jinja2_pdoc import Environment
env = Environment()
s = """
# jinja2-pdoc
embedd python code directly from pathlib using a jinja2 extension based on pdoc
## docstring from pathlib.Path
{% pdoc pathlib:Path:docstring %}
## source from pathlib.Path.open
```python
{% pdoc pathlib:Path.open:source.indent -%}
```
"""
code = env.from_string(textwrap.dedent(s)).render()
Path("example.md").write_text(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
## docstring from pathlib.Path
PurePath subclass that can make system calls.
Path represents a filesystem path but unlike PurePath, also offers
methods to do system calls on path objects. Depending on your system,
instantiating a Path will return either a PosixPath or a WindowsPath
object. You can also instantiate a PosixPath or WindowsPath directly,
but cannot instantiate a WindowsPath on a POSIX system or vice versa.
## source from pathlib.Path.open
```python
def open(self, mode='r', buffering=-1, encoding=None,
errors=None, newline=None):
"""
Open the file pointed by this path and return a file object, as
the built-in open() function does.
"""
if "b" not in mode:
encoding = io.text_encoding(encoding)
return io.open(self, mode, buffering, encoding, errors, newline)
```
````
## Syntax
`{% pdoc`[`<module>`](#module)`:`[`<object>`](#object)`:`[`<pdoc_attr[.str_attr]>`](#pdoc_attr)`%}`
### `<module>`
module name or path to python file, e.g.:
- `pathlib`
- `examples/example.py`
Example:
```jinja2
{% pdoc pathlib %}
```
### `<object>`
class and/or function names, eg. from `pathlib`:
- `Path`
- `Path.open`
Example:
```jinja2
{% pdoc pathlib:Path %}
```
### `<pdoc_attr>`
`pdoc` attributes:
- `docstring` - docstring of the object
- `source` - source code of the object
- `code` - plane code from functions, without def and docstring
Example:
```jinja2
{% pdoc pathlib:Path:docstring %}
```
### `[.str_attr]`
optional `str` functions can be added to `<pdoc_attr>` with a dot
- `dedent` - removes common leading whitespace, see `textwrap.dedent`
- `indent` - format code with 2 spaces for indentation, see `autopep8.fix_code`
- `upper` - converts to upper case
- `lower` - converts to lower case
- `nodoc` - removes shebang and docstring
Example:
```jinja2
{% pdoc pathlib:Path.open:code.dedent %}
```
## Command Line Interface
```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.
```
```console
>>> jinja2pdoc .\examples\*.jinja2
rendered examples\example.md.jinja2...................... .\example.md
```
## pre-commit hook
**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.
```yaml
repos:
- repo: https://github.com/d-chris/jinja2_pdoc/
rev: v1.1.0
hooks:
- id: jinja2pdoc
files: docs/.*\.jinja2$
```
Use `additional_dependencies` to add extra dependencies to the pre-commit environment. Example see below.
> This is necessary when a module or source code rendered into your template contains modules that are not part of the standard library.
```yaml
repos:
- repo: https://github.com/d-chris/jinja2_pdoc/
rev: v1.1.0
hooks:
- id: jinja2pdoc
files: docs/.*\.jinja2$
additional_dependencies: [pathlibutil]
```
## Dependencies
[](https://pypi.org/project/autopep8/)
[](https://pypi.org/project/click/)
[](https://pypi.org/project/jinja2/)
[](https://pypi.org/project/pdoc/)
[](https://pypi.org/project/PyYAML/)
---
Raw data
{
"_id": null,
"home_page": null,
"name": "jinja2-pdoc",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": null,
"keywords": "jinja2, pdoc, jinja2 extension, pre-commit-hook",
"author": "Christoph D\u00f6rrer",
"author_email": "d-chris@web.de",
"download_url": "https://files.pythonhosted.org/packages/1b/27/4d75d1189baf888570c7212bbd783b0894ed9c9d692b756479fc8b202f26/jinja2_pdoc-1.2.0.tar.gz",
"platform": null,
"description": "# jinja2-pdoc\n\n[](https://pypi.org/project/jinja2_pdoc/)\n[](https://pypi.org/project/jinja2_pdoc/)\n[](https://pypi.org/project/jinja2_pdoc/)\n[](https://raw.githubusercontent.com/d-chris/jinja2_pdoc/main/LICENSE)\n[](https://github.com/d-chris/jinja2_pdoc/actions/workflows/pytest.yml)\n[](https://d-chris.github.io/jinja2_pdoc)\n[](https://github.com/d-chris/jinja2_pdoc)\n[](https://codecov.io/gh/d-chris/jinja2_pdoc)\n[](https://github.com/pre-commit/pre-commit)\n\n---\n\n[`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.\n\nLazy loading of `docstrings`, `code` and `functions` directly from python modules into your `jinja2 template`.\n\n## Installation\n\n```cmd\npip install jinja2_pdoc\n```\n\n## Example\n\nCreate a markdown file with `docstrings` and `source code` from `pathlib.Path` using `jinja2` with `jinja2_pdoc` extension.\n\n### Python\n\n````python\nfrom jinja2_pdoc import Environment\n\nenv = Environment()\n\ns = \"\"\"\n # jinja2-pdoc\n\n embedd python code directly from pathlib using a jinja2 extension based on pdoc\n\n ## docstring from pathlib.Path\n\n {% pdoc pathlib:Path:docstring %}\n\n ## source from pathlib.Path.open\n\n ```python\n {% pdoc pathlib:Path.open:source.indent -%}\n ```\n \"\"\"\n\ncode = env.from_string(textwrap.dedent(s)).render()\n\nPath(\"example.md\").write_text(code)\n````\n\n### Markdown\n\noutput of the [python code](#python) above.\n\n````markdown\n\n# jinja2-pdoc\n\nembedd python code directly from pathlib using a jinja2 extension based on pdoc\n\n## docstring from pathlib.Path\n\nPurePath subclass that can make system calls.\n\nPath represents a filesystem path but unlike PurePath, also offers\nmethods to do system calls on path objects. Depending on your system,\ninstantiating a Path will return either a PosixPath or a WindowsPath\nobject. You can also instantiate a PosixPath or WindowsPath directly,\nbut cannot instantiate a WindowsPath on a POSIX system or vice versa.\n\n## source from pathlib.Path.open\n\n```python\ndef open(self, mode='r', buffering=-1, encoding=None,\n errors=None, newline=None):\n \"\"\"\n Open the file pointed by this path and return a file object, as\n the built-in open() function does.\n \"\"\"\n if \"b\" not in mode:\n encoding = io.text_encoding(encoding)\n return io.open(self, mode, buffering, encoding, errors, newline)\n```\n````\n\n## Syntax\n\n`{% pdoc`[`<module>`](#module)`:`[`<object>`](#object)`:`[`<pdoc_attr[.str_attr]>`](#pdoc_attr)`%}`\n\n### `<module>`\n\nmodule name or path to python file, e.g.:\n\n- `pathlib`\n- `examples/example.py`\n\nExample:\n\n```jinja2\n{% pdoc pathlib %}\n```\n\n### `<object>`\n\nclass and/or function names, eg. from `pathlib`:\n\n- `Path`\n- `Path.open`\n\nExample:\n\n```jinja2\n{% pdoc pathlib:Path %}\n```\n\n### `<pdoc_attr>`\n\n`pdoc` attributes:\n\n- `docstring` - docstring of the object\n- `source` - source code of the object\n- `code` - plane code from functions, without def and docstring\n\nExample:\n\n```jinja2\n{% pdoc pathlib:Path:docstring %}\n```\n\n### `[.str_attr]`\n\noptional `str` functions can be added to `<pdoc_attr>` with a dot\n\n- `dedent` - removes common leading whitespace, see `textwrap.dedent`\n- `indent` - format code with 2 spaces for indentation, see `autopep8.fix_code`\n- `upper` - converts to upper case\n- `lower` - converts to lower case\n- `nodoc` - removes shebang and docstring\n\nExample:\n\n```jinja2\n{% pdoc pathlib:Path.open:code.dedent %}\n```\n\n## Command Line Interface\n\n```console\n>>> jinja2pdoc --help\n\nUsage: jinja2pdoc [OPTIONS] [FILES]...\n\n Render jinja2 one or multiple template files, wildcards in filenames are\n allowed, e.g. `examples/*.jinja2`.\n\n If no 'filename' is provided in the frontmatter section of your file, e.g.\n '<!--filename: example.md-->'. All files are written to `output` directory\n and `suffixes` will be removed.\n\n To ignore the frontmatter section use the `--no-meta` flag.\n\nOptions:\n -o, --output PATH output directory for files, if no 'filename'\n is provided in the frontmatter. [default:\n cwd]\n -e, --encoding TEXT encoding of the files [default: utf-8]\n -s, --suffixes TEXT suffixes which will be removed from templates,\n if no 'filename' is provided in the\n frontmatter [default: .jinja2, .j2]\n --fail-fast exit on first error when rendering multiple\n file\n --meta / --no-meta parse frontmatter from the template, to search\n for 'filename' [default: meta]\n --rerender / --no-rerender Each file is rendered only once. [default:\n no-rerender]\n --silent suppress console output\n --load-path / --no-load-path add the current working directory to path\n [default: load-path]\n --help Show this message and exit.\n```\n\n```console\n>>> jinja2pdoc .\\examples\\*.jinja2\nrendered examples\\example.md.jinja2...................... .\\example.md\n```\n\n## pre-commit hook\n\n**Per default the hook is not registered to `files`!**\n\nTo render all template files from `docs` using `.pre-commit-config.yaml` add the following.\n\nYou 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.\n\n```yaml\nrepos:\n - repo: https://github.com/d-chris/jinja2_pdoc/\n rev: v1.1.0\n hooks:\n - id: jinja2pdoc\n files: docs/.*\\.jinja2$\n```\n\nUse `additional_dependencies` to add extra dependencies to the pre-commit environment. Example see below.\n\n> This is necessary when a module or source code rendered into your template contains modules that are not part of the standard library.\n\n```yaml\nrepos:\n - repo: https://github.com/d-chris/jinja2_pdoc/\n rev: v1.1.0\n hooks:\n - id: jinja2pdoc\n files: docs/.*\\.jinja2$\n additional_dependencies: [pathlibutil]\n```\n\n## Dependencies\n\n[](https://pypi.org/project/autopep8/)\n[](https://pypi.org/project/click/)\n[](https://pypi.org/project/jinja2/)\n[](https://pypi.org/project/pdoc/)\n[](https://pypi.org/project/PyYAML/)\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "jinja2 extension to embedd python code directly from module using pdoc",
"version": "1.2.0",
"project_urls": {
"documentation": "https://d-chris.github.io/jinja2_pdoc",
"repository": "https://github.com/d-chris/jinja2_pdoc"
},
"split_keywords": [
"jinja2",
" pdoc",
" jinja2 extension",
" pre-commit-hook"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7c2845821aedc571717409c8dae9d64eb698a58e0ca424749b2b5231bcb96e3c",
"md5": "1c80b9e9b2240aa9af6102db6f0f4a5e",
"sha256": "47663b8a3dc221a466fb6bea0d0e5fb3ae5b5f1fef60109f878011eb596d4a07"
},
"downloads": -1,
"filename": "jinja2_pdoc-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c80b9e9b2240aa9af6102db6f0f4a5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 10796,
"upload_time": "2024-10-25T18:08:46",
"upload_time_iso_8601": "2024-10-25T18:08:46.356551Z",
"url": "https://files.pythonhosted.org/packages/7c/28/45821aedc571717409c8dae9d64eb698a58e0ca424749b2b5231bcb96e3c/jinja2_pdoc-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b274d75d1189baf888570c7212bbd783b0894ed9c9d692b756479fc8b202f26",
"md5": "e207cf023690e93548abc64a9348e94e",
"sha256": "e039331d388bb1f8e56df153cdf68cc5c9d7c182fb45fab028d0ea40c2bf6726"
},
"downloads": -1,
"filename": "jinja2_pdoc-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e207cf023690e93548abc64a9348e94e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 10611,
"upload_time": "2024-10-25T18:08:47",
"upload_time_iso_8601": "2024-10-25T18:08:47.833737Z",
"url": "https://files.pythonhosted.org/packages/1b/27/4d75d1189baf888570c7212bbd783b0894ed9c9d692b756479fc8b202f26/jinja2_pdoc-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 18:08:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "d-chris",
"github_project": "jinja2_pdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jinja2-pdoc"
}
JSON
