mirror of https://github.com/Nonannet/pyladoc.git
149 lines
4.4 KiB
Markdown
149 lines
4.4 KiB
Markdown
# Pyladoc
|
|
|
|
## Description
|
|
Pyladoc is a Python package for programmatically generating HTML and
|
|
PDF/LaTeX output. This package specifically targets applications where reports
|
|
or results with Pandas tables and Matplotlib figures are generated
|
|
to be displayed as a website and as a PDF document without involving 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. The multiline string capability of Python
|
|
handles this very well. In comparison to "Code in Document" templates,
|
|
Python tools support this approach out of the box—similar to docstrings.
|
|
|
|
LaTeX is used as the backend for PDF generation. There are excellent engines for
|
|
rendering HTML to PDF, but even if there is no requirement for
|
|
accurate typesetting, placing programmatically generated content of variable
|
|
composition and element sizes on fixed-size pages without manual intervention
|
|
is a hard problem where LaTeX is superior.
|
|
|
|
## Example outputs
|
|
|
|
[](https://nonannet.github.io/pyladoc/files/test_latex_render1.pdf)
|
|
|
|
- HTML: [test_html_render1.html](https://nonannet.github.io/pyladoc/files/test_html_render1.html)
|
|
- PDF: [test_latex_render1.pdf](https://nonannet.github.io/pyladoc/files/test_latex_render1.pdf) ([LaTeX](https://nonannet.github.io/pyladoc/files/test_html_render1.tex))
|
|
|
|
The documents are generated by the script [tests/test_rendering_example1_doc.py](tests/test_rendering_example1_doc.py).
|
|
|
|
### 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 equations
|
|
|
|
### 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
|
|
- Tested on Linux and Windows
|
|
|
|
### Usage Scenarios
|
|
- Web services
|
|
- Report generation for lab equipment
|
|
|
|
## Installation
|
|
It can be installed with pip:
|
|
|
|
```bash
|
|
pip install pyladoc
|
|
```
|
|
|
|
As well as with conda:
|
|
```bash
|
|
conda install conda-forge::pyladoc
|
|
```
|
|
|
|
## Dependencies
|
|
Pyladoc depends on the markdown package.
|
|
|
|
Optional dependencies are:
|
|
- Matplotlib Python package for rendering LaTeX equations for HTML output
|
|
- LaTeX for exporting to PDF or exporting Matplotlib figures to LaTeX (PGF/TikZ rendering)
|
|
- Pandas and Jinja2 for rendering Pandas tables
|
|
- Matplotlib for rendering Matplotlib figures (obviously)
|
|
|
|
For the included template, the `miktex` LaTeX distribution works on Windows
|
|
and the following LaTeX setup works on Ubuntu (both tested in CI):
|
|
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install -y texlive-latex-extra texlive-fonts-recommended lmodern texlive-xetex texlive-science
|
|
```
|
|
|
|
## Usage
|
|
It is easy to use, as the following example code shows:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
git clone https://github.com/Nonannet/pyladoc.git
|
|
cd pyladoc
|
|
```
|
|
|
|
It's recommended to set up a venv:
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
|
|
```
|
|
|
|
Install the package and development dependencies while keeping files in the
|
|
current directory:
|
|
|
|
```bash
|
|
pip install -e .[dev]
|
|
```
|
|
|
|
Ensure that everything is set up correctly by running the tests:
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
## License
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |