diff --git a/.gitignore b/.gitignore index 5d381cc..42a45fc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,162 +1,9 @@ -# ---> Python -# Byte-compiled / optimized / DLL files +# Python __pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ +build *.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/#use-with-ide -.pdm.toml - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ +# Generated files +**/*.html +**/*.pdf diff --git a/README.md b/README.md index 84d7669..fe441f7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Cuddly -Generate HTML and PDF from KDL structed data. +Generate HTML and PDF files, with HTML and Jinja templates, from KDL structured data. ## Installation @@ -11,7 +11,7 @@ python -m venv env env/bin/pip install . ``` -## Usage +## Basic Usage ### Example @@ -26,15 +26,31 @@ Generating a HTML file env/bin/cuddly --template samples/cv/cv.template.html --input samples/cv.kdl --output samples/cv.html ``` -### Template usage +Generating both at the same time, with short options: -The template language used is [Jinja](https://jinja.palletsprojects.com/en/3.0.x/), source template need to be a single HTML template file. +``` +env/bin/cuddly -t samples/cv/cv.template.html -i samples/cv.kdl -o samples/cv.pdf -o samples/cv.html +``` -#### Base URL +### Samples -When generating the PDF the base URL is set to the source template directory. All relative links to other resources (for example CSS and images) must be relative to that directory. +* `samples/cv/cv.template.html`: Template to generate a CV, see `samples/cv.kdl` for the input data. +* `samples/facture/facture.template.html`: Template to generate a French invoice, see `samples/facture.kdl` for the input data. -#### Accessing nodes values and attributes + +## Template usage + +The source template need to be a single HTML template file. + +- The template language is [Jinja](https://jinja.palletsprojects.com/en/3.0.x/). +- For PDFs, the resulting HTML is run through [Weasyprint](https://weasyprint.org/). +- The data language is [KDL](https://kdl.dev/) (2.0.0). + +### Base URL + +When generating a PDF, the base URL is set to the source template directory. All relative links to other resources (for example CSS and images) must be relative to that directory. + +### Accessing nodes values and attributes Nodes are available as global variables in the template. The rendered value of a node is the first value that has been assigned to the node. This value can also be accessed using the `value` property. The list of values can be accessed using the `values` property. @@ -56,7 +72,23 @@ something something, other thing ``` -Accessing children nodes can be done using properties of the children names. +Attributes of a node can be accessed through the `attributes` property: + +```kdl +my_node version=42 "something" +``` + +```jinja +{{ my_node.attributes.version }} +``` +renders to +``` +42 +``` + +### Accessing children nodes + +Children nodes can be accessed using the children names. ```kdl my_node { @@ -73,7 +105,7 @@ renders to test ``` -If a node has multiple children of a same node type, then directly accessing the children properties will fail, a loop will be needed. Note that, on the other hand, looping on the children always work, even if there is only one child of the given type. +If a node has multiple children of a same node type, you’ll need to use a loop (directly accessing the children properties will fail). Note that, on the other hand, looping on the children always work, even if there is only one child of the given type. ```kdl my_node { @@ -85,7 +117,7 @@ my_node { ```jinja {% for node in my_node.other_node %} {{ node.value }} -{% endofr %} +{% endfor %} ``` renders to @@ -95,25 +127,11 @@ first second ``` -Attributes of a node can be accessed through the `attributes` property: +### Using components to template nodes -```kdl -my_node version=42 "something" -``` +You can define node specific templates inside the `components` tag in the HTML template file. Nodes can then be rendered using those micro-templates using the `render` filter. -```jinja -{{ my_node.attributes.version }} -``` -renders to -``` -42 -``` - -#### Templating nodes - -Node specific templates can be defined in the `components` element in the HTML template file. Nodes can then be rendered using those micro-templates using the `render` filter. - -The context of the micro-template is the node being rendered. As such, children and properties of that node are in the global scope. +The context of the micro-template is the node being rendered. As such, children and properties (`value`, `values`, `attributes`) of that node are in the global scope. ```kdl menu "Midnight meal" price="10 €" { @@ -133,7 +151,7 @@ menu "Midnight meal" price="10 €" {