jinja2-pdoc

jinja2 extension based on 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

pip install jinja2_pdoc

Example

Create a markdown file with docstrings and source code from pathlib.Path using jinja2 with jinja2_pdoc extension.

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

# 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>:<object>:<pdoc_attr[.str_attr]>%}

<module>

module name or path to python file, e.g.:

• pathlib
• examples/example.py

Example:

{% pdoc pathlib %}

<object>

class and/or function names, eg. from pathlib:

• Path
• Path.open

Example:

{% 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:

{% 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:

{% pdoc pathlib:Path.open:code.dedent %}

Filter

Filter to use in jinja2 template.

include

Environment.include - returns the content of the file.

{{ "path/to/file" | include(enc="utf-8") }}

shell

Environment.shell - run shell command and return the selected result from subprocess.CompletedProcess.

{{ "python --version" | shell(promt=">>> %s\n") }}

strip

Environment.strip - remove leading and trailing whitespace and newlines from a string.

{{ "path/to/file" | include | strip }}

Command Line Interface

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

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

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.

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!

- 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