Pyladoc classes, functions and submodules

DocumentWriter Class

class pyladoc.DocumentWriter

Bases: object

A class to create a document for exporting to HTML or LaTeX.

add_diagram(fig, caption='', ref_id='', prefix_pattern='Figure {}: ', ref_type='fig', centered=True)

Adds a diagram to the document.

Parameters:

fig (None) – The figure to add (matplotlib figure)
caption (str) – The caption for the figure
ref_id (str) – If provided, the figure can be referenced by this string
prefix_pattern (str) – A custom string for the caption prefix, {} will be replaced by the figure number
ref_type (str) – The type of reference. Each type (e.g., ‘fig’, ‘table’) has an individual numbering
centered (bool) – Whether to center the figure in LaTeX output

Return type:

None

add_document(doc)

Return type:: None

add_equation(latex_equation, ref_id='', ref_type='eq')

Adds a LaTeX equation to the document.

Parameters:

latex_equation (str) – LaTeX formatted equation
ref_id (str) – If provided, the equation is displayed with a number and can be referenced by the ref_id

Return type:

None

add_h1(text)

Adds a h1 heading to the document.

Parameters:: text (str) – The text of the heading
Return type:: None

add_h2(text)

Adds a h2 heading to the document.

Parameters:: text (str) – The text of the heading
Return type:: None

add_h3(text)

Adds a h3 heading to the document.

Parameters:: text (str) – The text of the heading
Return type:: None

add_html(text)

Adds HTML formatted text to the document. For the LaTeX export only basic HTML for text formatting and tables is supported.

Parameters:: text (str) – The HTML to add to the document
Return type:: None

add_markdown(text, section_class='')

Adds a markdown formatted text to the document.

Parameters:

text (str) – The markdown text to add
section_class (str) – The class for the text section

Return type:

None

add_table(table, caption='', ref_id='', prefix_pattern='Table {}: ', ref_type='table', centered=True)

Adds a table to the document.

Parameters:

table (None) – The table to add (pandas DataFrame or Styler)
caption (str) – The caption for the table
ref_id (str) – If provided, the table can be referenced by this string
prefix_pattern (str) – A custom string for the caption prefix, {} will be replaced by the table number
ref_type (str) – The type of reference. Each type (e.g., ‘fig’, ‘table’) has an individual numbering
centered (bool) – Whether to center the table in LaTeX output

Return type:

None

add_text(text, section_class='')

Adds a text paragraph to the document.

Parameters:

text (str) – The text to add
section_class (str) – The class for the paragraph

Return type:

None

new_field(name)

Return type:: DocumentWriter

to_html(figure_format='svg', base64_svgs=False, figure_scale=1)

Export the document to HTML. Figures will bew embedded in the HTML code. The format can be selected between png in base64, inline svg or svg in base64.

Parameters:

figure_format (Literal['svg', 'png', 'pgf']) – The format for embedding the figures in the HTML code (svg or png)
base64_svgs (bool) – Whether to encode svg images in base64

Return type:

str

Returns:

The HTML code

to_latex(font_family=None, table_renderer='simple', figure_scale=1)

Export the document to LaTeX. Figures will be embedded as pgf graphics.

Parameters:

font_family (Literal[None, 'serif', 'sans-serif']) – Overwrites the front family for figures
table_renderer (Literal['pandas', 'simple']) – The renderer for tables (simple: renderer with column type guessing for text and numbers; pandas: using the internal pandas LaTeX renderer)

Return type:

str

Returns:

The LaTeX code

to_pdf(file_path, font_family=None, table_renderer='simple', latex_template_path='', figure_scale=1, engine='pdflatex')

Export the document to a PDF file using LaTeX.

Parameters:

file_path (str) – The path to save the PDF file to
font_family (Literal[None, 'serif', 'sans-serif']) – Overwrites the front family for figures and the template
latex_template_path (str) – Path to a LaTeX template file. The expression <!–CONTENT–> will be replaced by the generated content. If no path is provided a default template is used.
engine (Literal['pdflatex', 'lualatex', 'xelatex', 'tectonic']) – LaTeX engine (pdflatex, lualatex, xelatex or tectonic)

Return type:

bool

Returns:

True if the PDF file was successfully created

Functions

pyladoc.escape_html(text)

Escapes special HTML characters in a given string.

Parameters:: text (str) – The text to escape
Return type:: str
Returns:: Escaped text save for inserting into HTML code

pyladoc.figure_to_string(fig, unique_id, figure_format='svg', font_family=None, scale=1, alt_text='', base64=False)

Converts a matplotlib figure to a ascii-string. For png base64 encoding is used in general, for svg base64 encoding can be enabled. For base64 encoded figures a img-tag is included in the output.

Parameters:

fig (None) – The figure to convert
figure_format (Literal['svg', 'png', 'pgf']) – The format to save the figure in (svg, png or pgf)
font_family (str | None) – The font family to use for the figure
scale (float) – Scaling factor for the figure size
alt_text (str) – The alt text for the figure
base64 (bool) – If the format is svg this determine if the image is encode in base64

Return type:

str

Returns:

The figure as ascii-string

pyladoc.inject_to_template(content, template_path='', internal_template='')

injects a content string into a template. The placeholder <!–CONTENT–> will be replaced by the content. If the placeholder is prefixed with a ‘%’ comment character, this character will be replaced as well.

Parameters:

template_path (str) – Path to a template file
internal_template (str) – Path to a internal default template

Return type:

str

Returns:

Template with included content

pyladoc.latex_to_figure(latex_code)

Return type:: None

Submodule latex

pyladoc.latex.basic_formatter(value)

Return type:: str

pyladoc.latex.compile(latex_code, output_file='', encoding='utf-8', engine='pdflatex')

Compiles LaTeX code to a PDF file.

Parameters:

latex_code (str) – The LaTeX code to compile.
output_file (str) – The output file path.
encoding (str) – The encoding of the LaTeX code.
engine (Literal['pdflatex', 'lualatex', 'xelatex', 'tectonic']) – LaTeX engine (pdflatex, lualatex, xelatex or tectonic)

Returns:

A boolean indicating whether the compilation was successful.
A list of errors.
A list of warnings.

Return type:

A tuple with three elements

pyladoc.latex.escape_text(text)

Escapes special LaTeX characters and often used unicode characters in a given string.

Parameters:: text (str) – The text to escape
Return type:: str
Returns:: Escaped text

pyladoc.latex.from_html(html_code)

Converts HTML code to LaTeX code using HTMLParser.

Parameters:: html_code (str) – The HTML code to convert.
Return type:: str
Returns:: The LaTeX code.

pyladoc.latex.get_equation_code(equation, reference, block=False)

Converts an equation string to LaTeX code.

Parameters:

equation (str) – The LaTeX equation string.
reference (str | None) – The reference type and ID for the equation separated by a ‘:’.

Return type:

str

pyladoc.latex.inject_latex_command(text, command)

Return type:: str

pyladoc.latex.normalize_label_text(text)

Replace any special non-allowed character in the lable text.

Parameters:: text (str) – Input text
Return type:: str
Returns:: Normalized text

pyladoc.latex.render_pandas_styler_table(df_style, caption='', label='', centering=True)

Converts a pandas Styler object to LaTeX table.

Parameters:

df_style (None) – The pandas Styler object to convert.
caption (str) – The caption for the table.
label (str) – Label for referencing the table.
centering (bool) – Whether to center the table.

Return type:

str

Returns:

The LaTeX code.

pyladoc.latex.to_ascii(text)

Replaces/escapes often used unicode characters in LaTeX code or text with its LaTeX ascii equivalents.

Parameters:: text (str) – The text to convert.
Return type:: str
Returns:: The escaped text.