pyladoc 1.1.0

Package for generating HTML and PDF/latex from python code

Pyladoc

Description

Pyladoc is a python package for programmatically generating HTML and PDF/LaTeX output. This package targets specifically applications where reports or results with Pandas-tables and Matplotlib-figures are generated programmatically to be displayed as website and as PDF document without any manual formatting steps.

This package focuses on the "Document in Code" approach for cases where a lot of calculations and data handling is done but not a lot of document text needs to be displayed.

As backend for PDF generation LaTeX is used. There are excellent engines for rendering HTML to PDF available, but even if there is no requirement for an accurate typesetting, placing programmatically content of variable composition and element sizes on fixed size pages without manual intervention is a hard problem that LaTeX is very capable of.

Example outputs

The following documents are generated by tests/test_rendering_example1_doc.py:

• HTML: test_html_render1.html
• PDF: test_latex_render1.pdf

Supported primitives

• Text (can be Markdown or HTML formatted)
• Headings
• Tables (Pandas, Markdown or HTML)
• Matplotlib figures
• LaTeX equations (Block or inline)
• Named references for figures, tables and equation

Key Features

• HTML and PDF/LaTeX rendering of the same document
• Single file output including figures
• Figure and equation embedding in HTML by inline SVG, SVG in Base64 or PNG in Base64
• Figure embedding in LaTeX as PGF/TikZ

Usage Scenarios

• Webservices
• Report generation for lab equipment

Installation

It can be installed with pip:

pip install pyladoc

Usage

It is easy to use as the following example code shows:

import pyladoc
import pandas as pd

doc = pyladoc.DocumentWriter()

doc.add_markdown("""
    # Example
    This is inline LaTeX: $$\\lambda$$

    This is a LaTeX block with a number:
    $$
    \\label{eq:test1}
    \\lambda_{\text{mix}} = \\sum_{i=1}^{n} \\frac{x_i \\lambda_i}{\\sum_{j=1}^{n} x_j \\Phi_{ij}}
    $$

    This is an example table. The table @table:pandas_example shows some random data.
    """)

some_data = {
    'Row1': ["Line1", "Line2", "Line3"],
    'Row2': [120, 100, 110],
    'Row3': ['12 g/km', '> 150 g/km', '110 g/km']
}
df = pd.DataFrame(some_data)
doc.add_table(df, 'This is a pandas example table', 'pandas_example')

html_code = doc.to_html()
print(html_code)

doc.to_pdf('test.pdf')

Contributing

Contributions are welcome, please open an issue or submit a pull request on GitHub.

Developer Guide

To get started with developing the pyladoc package, follow these steps.

First, clone the repository to your local machine using Git:

git clone https://github.com/Nonannet/pyladoc.git
cd pyladoc

It's recommended to setup an venv:

python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

Install the package and dev-dependencies while keeping files in the current directory:

pip install -e .[dev]

Ensure that everything is set up correctly by running the tests:

pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.