Installation and Usage¶

TL;DR¶

First install the prerequisites then ...

pip install docma

# Optionally, add duckdb and lava support
pip install 'docma[duckdb]'
pip install 'docma[lava]'

# Check docma installed ok
docma --help

# Create our first docma template. This is a working basic template.
docma new my-template

# Compile it
docma compile -i my-template -t my-template.zip

# Render it to PDF.
docma pdf -t my-template.zip -o my-doc.pdf

Prerequisites¶

PythonmacOSLinuxDOS

Docma requires Python3.11.

GTK is required for the HTML to PDF process.

brew install gtk+

If DuckDB data sources are used, install the DuckDB CLI.

brew install duckdb

Pango is required for the HTML to PDF process.

If DuckDB data sources are used, install the DuckDB CLI. The Python API will be installed automatically when docma is installed.

Docma might work on DOS. How would I know? Why would I care? I guess you could try WSL 2. If you do, please let us know.

Installing Docma¶

Installing with Pip¶

Basic install:

pip install docma

This will install the base docma Python package and the docma CLI. This will not install support for duckdb or lava data providers.

To install support for the duckdb data provider:

pip install 'docma[duckdb]'

To install support for the lava data provider:

pip install 'docma[lava]'

Installing from the Repo¶

Clone the docma repo.

The rest of the setup is handled by the Makefile.

# Create venv and install the required Python packages
make init
# Activate the virtual environment
source venv/bin/activate

To run the docma CLI directly from the repo:

python3 -m docma.cli.docma --help

To build docma, use the Makefile.

# See what we can build ...
make
# ... or ....
make help

To build an install bundle:

make pkg

Docker¶

The repo includes support for building a docker container on an Amazon Linux 2023 base with docma installed. To build the image:

make docker

This will include support for the duckdb data provider, but not the lava data provider.

This image is also available from Docker Hub:

docker pull jingizmo/docma`

Info

The basic image doesn't add any fonts to the minimal set already available in the Amazon Linux 2023 image. To add fonts, build your own image on the docma base image. A better alternative is to include important fonts within document templates to avoid any dependency on host fonts. See Fonts.

The Docma CLI¶

The docma CLI provides everything required to compile and render document templates.

# Get help
docma --help

It supports the following sub-commands.

Command	Description
compile	Compile a source directory into a document template.
html	Render a document template to PDF.
html-batch	Render a batch of HTML documents from a single document template.
info	Print information about a document template.
new	Create a new docma template source directory.
pdf	Render a document template to PDF.
pdf-batch	Render a batch of PDF documents from a single document template.

Each sub-command has its own help:

docma compile --help

A typical usage sequence might be:

# First create the source for the document template in its own directory
docma new my-template

# Add content, configuration etc. Then ...

# Compile
docma compile -i my-template -t my-template.zip

# Render to PDF
docma pdf -t my-template.zip -o my-doc.pdf --file parameters.yaml

# Render to HTML
docma html -t my-template.zip -o my-doc.pdf --file parameters.yaml

Creating a New Document Template¶

To create a new docma template directory:

docma new <DIRECTORY>

This will prompt the user to enter a small number of configuration parameters. They are all mandatory. Do not leave anything blank.

The specified directory will now contain a very simple, but complete, document template source directory that can be compiled and rendered:

docma compile -i <DIRECTORY> -t my-template.zip
docma pdf -t my-template.zip -o my-doc.pdf

Docma Python API¶

The API is quite basic:

from docma import compile_template, render_template_to_pdf

template_src_dir = 'a/b/c'
template_location = 'my-template.zip'  # ... or a directory when experimenting
pdf_location = 'my-doc.pdf'
params = {...}  # A Dict of parameters.

compile_template(template_src_dir, template_location)

pdf = render_template_to_pdf(template_location, params)

# We now have a pypdf PdfWriter object. Do with it what you will. e.g.
pdf.write(pdf_location)

Refer to the API documentation for more information.

Building the Documentation¶

Docma comes with this user guide and auto-generated API documentation.

To build the documentation:

make doc

The generated documentation is placed in the dist/doc directory.

To see the documentation locally:

make serve

This uses mkdocs to run a local server on http://127.0.0.1:8000/.

If editing the documentation, ensure that a spell check is done as part of the process using:

make spell

This requires the aspell tool. For macOS:

brew install aspell

Running Unit Tests¶

The unit tests require some docker based components (Postgres, web server etc.) to be up and running. These require a .env file containing credentials for test accounts etc. In the main directory, copy dot-env-sample to .env and edit it to add passwords in the indicated spots. The values don't really matter as the accounts will be created as part of each test session. Even so, do not add .env to the repo. It's bad form.

To run the tests:

# Start the docker components. This will take a while on first invocation as it
# needs to download base images and build some stuff on them.
make up

# Run tests 
make test

# Get a coverage report 
make coverage

# Check the coverage report (on a Mac)
open -a Safari dist/test/htmlcov/index.html

# Stop the docker components when done
make down