Metadata-Version: 2.1
Name: jinja2-pdoc
Version: 0.1.0
Summary: jinja2 extension to embedd python code directly from module using pdoc
License: MIT
Keywords: jinja2,pdoc,jinja2 extension
Author: Christoph Dörrer
Author-email: d-chris@web.d
Requires-Python: >=3.8.1,<3.12
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: Jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: pdoc (>=14.3.0,<15.0.0)
Project-URL: documentation, https://github.com/d-chris/jinja2_pdoc
Project-URL: homepage, https://github.com/d-chris/jinja2_pdoc
Project-URL: repository, https://github.com/d-chris/jinja2_pdoc
Description-Content-Type: text/markdown

# jinja2-pdoc

[![Github](https://img.shields.io/website?url=https%3A%2F%2Fgithub.com%2Fd-chris%2Fjinja2_pdoc&logo=github&label=github)
](https://www.github.com/d-chris/jinja2_pdoc)
[![PyPI - License](https://img.shields.io/pypi/l/pathlibutil)](https://raw.githubusercontent.com/d-chris/jinja2_pdoc/main/LICENSE)
---

[`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.

## Installation

```cmd
pip install jinja2_pdoc
```

## Usage

- [CLI](#command-line)
- [Library](#library)

## Syntax


```jinja2
{% pdoc <module>::<object>:<pdoc_attr[.str_attr]> %}
```
see also [Example](#library)

### `<module>`

module name or path to python file

- `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`
- `upper` - converts to upper case
- `lower` - converts to lower case

Example:

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

## Examples

### Command Line

```cmd
>>> jinja2pdoc .\examples\ --force

rendering.. example.md
```

```cmd

>>> jinja2pdoc --help

Usage: jinja2pdoc [OPTIONS] INPUT [OUTPUT]

  Render jinja2 templates from a input directory or file and write to a output
  directory.

  if the `input` is a directory, all files with a matching `pattern` are
  renderd.

  if no `output` is given, the current working directory is used.

Options:
  -p, --pattern TEXT  template search pattern for directories
  -f, --force         overwrite existing files
  -n, --newline TEXT  newline character
  --help              Show this message and exit..
```

### Library

python code to render a template directly from a string

```python
from jinja2_pdoc import jinja2, PdocJinja2

env = jinja2.Environment(extensions=[PdocJinja2])

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.dedent -%}
    ```
    """

code = env.from_string(textwrap.dedent(s)).render()

Path("example.md").write_text(code)

```

### Result

output of the [code](#library) 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)

```
````

