From 5f6147c2b9422f4057c9fdbd0dbd4325754ee5ad Mon Sep 17 00:00:00 2001 From: Nicolas Date: Wed, 25 Jun 2025 08:36:32 +0200 Subject: [PATCH] Readme updated (- conda added for installing) --- README.md | 47 ++++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 8969ea0..2a5f59d 100644 --- a/README.md +++ b/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,17 +34,17 @@ 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 ### Usage Scenarios -- Webservices +- Web services - Report generation for lab equipment ## Installation @@ -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