mirror of https://github.com/Nonannet/pyladoc.git
Readme updated (- conda added for installing)
This commit is contained in:
Nicolas
parent
6120a38241
commit
5f6147c2b9
45
README.md
45
README.md
|
|
@ -1,22 +1,22 @@
|
|||
# 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
|
||||
to be displayed as website and as PDF document without involving any manual
|
||||
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 supports this approach out of the box - similar doch docstrings.
|
||||
handles this very well. In comparison to "Code in Document" templates,
|
||||
Python tools support this approach out of the box—similar to docstrings.
|
||||
|
||||
As backend for PDF generation LaTeX is used. There are excellent engines for
|
||||
rendering HTML to PDF, but even if there is no requirement for an
|
||||
accurate typesetting and what not, placing programmatically content of variable
|
||||
composition and element sizes on fixed size pages without manual intervention
|
||||
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
|
||||
|
|
@ -34,12 +34,12 @@ The documents are generated by the script [tests/test_rendering_example1_doc.py]
|
|||
- Tables (Pandas, Markdown or HTML)
|
||||
- Matplotlib figures
|
||||
- LaTeX equations (block or inline)
|
||||
- Named references for figures, tables and equations
|
||||
- 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 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
|
||||
|
||||
|
|
@ -54,16 +54,21 @@ It can be installed with pip:
|
|||
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
|
||||
- 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)
|
||||
- Pandas and Jinja2 for rendering Pandas tables
|
||||
- Matplotlib for rendering Matplotlib figures (obviously)
|
||||
|
||||
For the included template the `miktex`-LaTeX distribution works on Windows
|
||||
For the included template, the `miktex` LaTeX distribution works on Windows
|
||||
and the following LaTeX setup works on Ubuntu (both tested in CI):
|
||||
|
||||
```bash
|
||||
|
|
@ -72,7 +77,7 @@ sudo apt-get install -y texlive-latex-extra texlive-fonts-recommended lmodern te
|
|||
```
|
||||
|
||||
## Usage
|
||||
It is easy to use as the following example code shows:
|
||||
It is easy to use, as the following example code shows:
|
||||
|
||||
```python
|
||||
import pyladoc
|
||||
|
|
@ -108,7 +113,7 @@ doc.to_pdf('test.pdf')
|
|||
```
|
||||
|
||||
## Contributing
|
||||
Contributions are welcome, please open an issue or submit a pull request on GitHub.
|
||||
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.
|
||||
|
|
@ -120,14 +125,14 @@ git clone https://github.com/Nonannet/pyladoc.git
|
|||
cd pyladoc
|
||||
```
|
||||
|
||||
It's recommended to setup an venv:
|
||||
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 dev-dependencies while keeping files in the
|
||||
Install the package and development dependencies while keeping files in the
|
||||
current directory:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
Loading…
Reference in New Issue