NOTE: This tutorial was auto generated using the QWEN 3.6 Large Language Model

Library Configuration

pydocmaker provides a set of configuration functions to control output rendering, PDF generation engines, LaTeX compilers, and LibreOffice paths. All configuration functions follow a consistent config_<feature>_get() and config_<feature>_set() pattern.

You can also access them via the pyd.options convenience class, e.g. pyd.options.pdf_engine_get().

[1]:

import pydocmaker as pyd
print(pyd.__version__)

2.6.9

Renderer Configuration

The renderer controls how reports are displayed inline within Python (e.g. in Jupyter notebooks). The available options are:

Option	Description
`auto`	Automatically chosen based on environment (default)
`rich`	Use the Rich library for styled Console output
`md`	Markdown-formatted output
`html`	HTML-formatted output
`pdf`	Render as PDF

Getting the current renderer

[2]:

pyd.config_renderer_default_get()

[2]:

'auto'

Changing the renderer

[3]:

pyd.config_renderer_default_set('rich')
pyd.config_renderer_default_get()

[3]:

'rich'

The function returns the selected renderer, and raising a ValueError if an invalid option is passed.

PDF Engine Configuration

pydocmaker supports multiple backends for generating PDF documents. The available PDF engines are:

Engine	Description
`typst`	Typst typesetting system (default)
`tex`	LaTeX via pdflatex/lualatex/xelatex
`word`	Microsoft Word via COM automation (Windows only)
`libreoffice`	LibreOffice headless conversion
`pandoc`	Pandoc document converter

Getting the current PDF engine

If no engine has been explicitly set, calling config_pdf_engine_get() will trigger auto-detection to find the first available engine on your system:

[4]:

pyd.config_pdf_engine_get()

[4]:

'typst'

Scanning for available engines

You can scan the system to see which PDF engines are actually installed and available:

[5]:

# Return list of all available engines
pyd.config_pdf_engine_scan()

[5]:

['typst', 'tex', 'word', 'libreoffice', 'pandoc']

[6]:

# Return only the first available engine
pyd.config_pdf_engine_scan(firstonly=True)

[6]:

'typst'

Setting the PDF engine explicitly

If you know which engine you want to use, set it directly:

[7]:

pyd.config_pdf_engine_set('typst')
pyd.config_pdf_engine_get()

[7]:

'typst'

Testing engine availability

You can test whether the currently configured PDF engine is actually available on your system. By default, it raises a ValueError if no valid compiler is found:

[8]:

try:
    result = pyd.config_pdf_engine_test(raise_on_error=True)
    print(f"Test passed: {result}")
except ValueError as e:
    print(f"No valid PDF engine found: {e}")

Test passed: True

With raise_on_error=False, it simply returns True or False:

[9]:

pyd.config_pdf_engine_test(raise_on_error=False)

[9]:

True

LaTeX Compiler Configuration

When using the tex PDF engine, pydocmaker needs a LaTeX compiler. The supported compilers are:

Compiler	Description
`pdflatex`	Standard PDFLaTeX
`lualatex`	LuaLaTeX (Lua support)
`xelatex`	XeLaTeX (Unicode/font support)

Getting the current compiler

[10]:

pyd.config_latex_compiler_get()

[10]:

'pdflatex'

If no compiler has been set, this triggers auto-detection to find the first available one.

Scanning for available compilers

[11]:

pyd.config_latex_compiler_scan()

[11]:

['pdflatex', 'lualatex', 'xelatex']

Setting the compiler explicitly

You can force a specific compiler (it must be installed on your system):

[12]:

pyd.config_latex_compiler_set('xelatex')
pyd.config_latex_compiler_get()

[12]:

'xelatex'

LibreOffice Path Configuration

When using the libreoffice PDF engine, pydocmaker needs to locate the LibreOffice executable. These functions help you manage that path.

Finding the LibreOffice path

[13]:

pyd.config_libreoffice_path_find()

[13]:

'C:\\Program Files\\LibreOffice\\program\\soffice.exe'

Getting the current path

[14]:

pyd.config_libreoffice_path_get()

[14]:

'C:\\Program Files\\LibreOffice\\program\\soffice.exe'

Setting a custom path

If LibreOffice is installed in a non-standard location, you can set it explicitly:

[15]:

# pyd.config_libreoffice_path_set(r'C:\Program Files\LibreOffice\program\soffice.exe')
# pyd.config_libreoffice_path_get()

Passing None forces pydocmaker to re-resolve the path on the next call.

Convenience Functions

pyd.options class

For a cleaner namespace, you can access all config functions through the pyd.options class:

[16]:

pyd.options.pdf_engine_get()
pyd.options.pdf_engine_set('typst')
pyd.options.latex_compiler_get()
pyd.options.renderer_default_get()

[16]:

'rich'

pyd.info_optionals()

Get a comprehensive overview of all optional dependencies and their status in one call:

[17]:

pyd.info_optionals()

[17]:

{'can_run_pandoc': True,
 'can_use_w32_word': True,
 'can_use_libreoffice': True,
 'pdf_engines_available': ['typst', 'tex', 'word', 'libreoffice', 'pandoc'],
 'pdf_engine': 'typst',
 'libreoffice_path': 'C:\\Program Files\\LibreOffice\\program\\soffice.exe',
 'typst_installed': True}

This returns a dictionary with:

Key	Description
`can_run_pandoc`	Whether pandoc is available
`can_use_w32_word`	Whether Word COM automation works (Windows)
`can_use_libreoffice`	Whether LibreOffice is available
`pdf_engines_available`	List of all available PDF engines
`pdf_engine`	Currently selected PDF engine
`libreoffice_path`	Path to LibreOffice executable
`typst_installed`	Whether Typst is installed

Working Example

Here is a complete example showing how to configure pydocmaker for PDF output. First check what engines are available, then set your preferred engine:

[18]:

# Check available engines
available = pyd.config_pdf_engine_scan()
print(f"Available PDF engines: {available}")

# Set your preferred engine
if 'typst' in available:
    pyd.config_pdf_engine_set('typst')
    print("Selected Typst as PDF engine.")
elif 'tex' in available:
    pyd.config_pdf_engine_set('tex')
    print("Selected LaTeX as PDF engine.")
elif 'pandoc' in available:
    pyd.config_pdf_engine_set('pandoc')
    print("Selected Pandoc as PDF engine.")
else:
    pyd.config_pdf_engine_test(raise_on_error=True)
    print("Auto-detected a PDF engine.")

Available PDF engines: ['typst', 'tex', 'word', 'libreoffice', 'pandoc']
Selected Typst as PDF engine.

Pandoc Configuration

When using pandoc, you can control which pandoc executables are considered allowed:

[19]:

pyd.config_pandoc_allowed_get()

[19]:

True

[20]:

# pyd.config_pandoc_allowed_set(['pandoc', 'pandoc-lua'])

The helper functions pyd.pandoc_set_enabled() and pyd.pandoc_set_disabled() provide a quick way to allow or disallow pandoc as a conversion option.