jinja2-pdoc 1.3.0
jinja2 extension to embedd python code directly from module using pdoc
License: MIT
Requires Python: <4.0.0,>=3.8.1
Keywords: jinja2, pdoc, jinja2 extension, pre-commit-hook

# 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
from jinja2_pdoc import Environment

env = Environment()

template = """\
# 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(template).render()

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

## 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 self._accessor.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 %}
```

## 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
$ 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

  No files found.
```

## 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
repos:
  - repo: https://github.com/d-chris/jinja2_pdoc/
    rev: v1.1.0
    hooks:
      - id: jinja2pdoc
        files: docs/.*\.jinja2$
```

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
- 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

[![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/)

---