# Pyladoc classes, functions and submodules — pyladoc documentation

# 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.