nicolas
/
pyladoc
mirror of https://github.com/Nonannet/pyladoc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Readme updated

This commit is contained in:
Nicolas 2025-04-14 21:16:43 +02:00
parent e91c70880b
commit 413be9b625
1 changed files with 23 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@ -3,39 +3,42 @@
## Description ## Description
Pyladoc is a python package for programmatically generating HTML and Pyladoc is a python package for programmatically generating HTML and
PDF/LaTeX output. This package targets specifically applications where reports PDF/LaTeX output. This package targets specifically applications where reports
or results with Pandas-tables and Matplotlib-figures are generated programmatically or results with Pandas-tables and Matplotlib-figures are generated
to be displayed as website and as PDF document without any manual formatting to be displayed as website and as PDF document without involving any manual
steps. formatting steps.
This package focuses on the "Document in Code" approach for cases 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 where a lot of calculations and data handling is done but not a lot of
document text needs to be displayed. 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 supports this approach out of the box.
As backend for PDF generation LaTeX is used. There are excellent engines for 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 rendering HTML to PDF, but even if there is no requirement for an
accurate typesetting, placing programmatically content of variable accurate typesetting and what not, placing programmatically content of variable
composition and element sizes on fixed size pages without manual intervention composition and element sizes on fixed size pages without manual intervention
is a hard problem that LaTeX is very capable of. is a hard problem where LaTeX is superior.
## Example outputs ## Example outputs
The following documents are generated by [tests/test_rendering_example1_doc.py](tests/test_rendering_example1_doc.py):
- HTML: [test_html_render1.html](https://html-preview.github.io/?url=https://github.com/Nonannet/pyladoc/blob/main/tests/out/test_html_render1.html) - HTML: [test_html_render1.html](https://html-preview.github.io/?url=https://github.com/Nonannet/pyladoc/blob/main/tests/out/test_html_render1.html)
- PDF: [test_latex_render1.pdf](https://raw.githubusercontent.com/Nonannet/pyladoc/refs/heads/main/tests/out/test_latex_render1.pdf) - PDF: [test_latex_render1.pdf](https://raw.githubusercontent.com/Nonannet/pyladoc/refs/heads/main/tests/out/test_latex_render1.pdf)
The documents are generated by the script [tests/test_rendering_example1_doc.py](tests/test_rendering_example1_doc.py).
### Supported primitives ### Supported primitives
- Text (can be Markdown or HTML formatted) - Text (can be Markdown or HTML formatted)
- Headings - Headings
- Tables (Pandas, Markdown or HTML) - Tables (Pandas, Markdown or HTML)
- Matplotlib figures - Matplotlib figures
- LaTeX equations (Block or inline) - LaTeX equations (block or inline)
- Named references for figures, tables and equation - Named references for figures, tables and equations
### Key Features ### Key Features
- HTML and PDF/LaTeX rendering of the same document - HTML and PDF/LaTeX rendering of the same document
- Single file output including figures - Single file output including figures
- Figure and equation embedding in HTML by inline SVG, SVG in Base64 or PNG in Base64 - Figure and equation embedding in HTML by inline SVG, SVG in Base64 or PNG in Base64
- Figure embedding in LaTeX as PGF/TikZ - Figure embedding in LaTeX as PGF/TikZ
- Tested on Linux and Windows
### Usage Scenarios ### Usage Scenarios
- Webservices - Webservices
@ -48,6 +51,14 @@ It can be installed with pip:
pip install pyladoc pip install 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 Matplotlib for including Pandas Tables and Matplotlib figures (obviously)
## Usage ## Usage
It is easy to use as the following example code shows: It is easy to use as the following example code shows:
@ -116,6 +127,6 @@ Ensure that everything is set up correctly by running the tests:
```bash ```bash
pytest pytest
``` ```
## License ## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.