Merge pull request #1 from d-chris/develop

pre release

Author: d-chris

README.md

@@ -1,22 +1,30 @@
 # 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
 
-```bash
+```cmd
 pip install jinja2_pdoc
 ```
 
+## Usage
+
+- [CLI](#command-line)
+- [Library](#library)
+
 ## Syntax
 
-see [Example](#code) down below
 
 ```jinja2
 {% pdoc <module>::<object>:<pdoc_attr[.str_attr]> %}
 ```
+see also [Example](#library)
 
 ### `<module>`
 
@@ -55,27 +63,55 @@ Example:
 Example:
 
 ```jinja2
-{% pdoc pathlib::Path:docstring.source %}
+{% pdoc pathlib::Path:docstring %}
 ```
 
-### `str_attr`
+### `[.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:docstring.dedent %}
+{% pdoc pathlib::Path.open:code.dedent %}
 ```
 
-## Usage
+## Examples
+
+### Command Line
+
+```cmd
+>>> jinja2pdoc .\examples\ --force
+
+rendering.. example.md
+```
+
+```cmd
 
-### Code
+>>> 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
 
@@ -90,23 +126,25 @@ s = """
     embedd python code directly from pathlib using a jinja2 extension based on pdoc
 
     ## docstring from pathlib.Path
-    {% pdoc pathlib::Path:docstring.dedent -%}
+
+    {% 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("jinja2_pdoc.md").write_text(code)
+Path("example.md").write_text(code)
 
 ```
 
 ### Result
 
-output of the code above
+output of the [code](#library) above
 
 ````markdown
 # jinja2-pdoc

examples/example.md.jinja2

@@ -0,0 +1,13 @@
+# 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 -%}
+```

jinja2_pdoc/__init__.py

@@ -0,0 +1,6 @@
+import jinja2
+import pdoc
+
+from jinja2_pdoc.extension import PdocJinja2
+
+__all__ = ["PdocJinja2", "jinja2", "pdoc"]

jinja2_pdoc/cli.py

@@ -0,0 +1,90 @@
+from pathlib import Path
+from typing import Generator, Iterable, Tuple
+
+import click
+
+from jinja2_pdoc import PdocJinja2, jinja2
+
+
+def eof_newline(content: str, eof: str = "\n") -> str:
+    """
+    make sure the file content ends with a newline if specified.
+    """
+    if content.endswith(eof) or not eof:
+        return content
+
+    return content + eof
+
+
+def load_files(
+    files: Iterable[Path], out_dir: Path, force: bool
+) -> Generator[Tuple[str, Path], None, None]:
+    """
+    iterates over files and yield `(content,  out_file)` if its not existing.
+
+    if `force` is True, all files are proessed.
+    """
+    for file in files:
+        out = out_dir.joinpath(file.stem).resolve()
+
+        if not out.is_file() or force:
+            yield (file.read_text(), out)
+            click.echo(f"rendering.. {out}")
+        else:
+            click.echo(f"skip....... {out}")
+    else:
+        click.echo("\n......done")
+
+
+@click.command()
+@click.argument("input", type=click.Path(exists=True))
+@click.argument("output", type=click.Path(file_okay=False), default=Path.cwd())
+@click.option(
+    "-p",
+    "--pattern",
+    default="*.jinja2",
+    help="template search pattern for directories",
+)
+@click.option("-f", "--force", is_flag=True, help="overwrite existing files")
+@click.option(
+    "-n",
+    "--newline",
+    default="\n",
+    help="newline character",
+)
+def main(
+    input: str,
+    output: str = ".",
+    pattern: str = "*.jinja2",
+    force: bool = False,
+    newline: str = "\n",
+) -> None:
+    """
+    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.
+    """
+
+    env = jinja2.Environment(extensions=[PdocJinja2])
+
+    input = Path(input)
+    output = Path(output)
+    output.mkdir(parents=True, exist_ok=True)
+
+    if input.is_file():
+        files = [
+            input,
+        ]
+    else:
+        files = input.rglob(pattern)
+
+    for content, file in load_files(files, output, force):
+        code = env.from_string(content).render()
+        file.write_text(eof_newline(code, newline))
+
+
+if __name__ == "__main__":
+    main()