API Reference

This section provides detailed API documentation for typsphinx.

Builders

Typst builder for Sphinx.

This module implements the TypstBuilder class, which is responsible for building Typst output from Sphinx documentation.

class typsphinx.builder.TypstBuilder(app, env)

Bases: Builder

Builder class for Typst output format.

This builder converts Sphinx documentation to Typst markup files (.typ), which can then be compiled to PDF using the Typst compiler.

Parameters:

• app (Sphinx)

• env (BuildEnvironment)

name: str = 'typst'

The builder’s name. This is the value used to select builders on the command line.

format: str = 'typst'

The builder’s output format, or ‘’ if no document output is produced. This is commonly the file extension, e.g. “html”, though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

out_suffix = '.typ'

allow_parallel: bool = True

Whether it is safe to make parallel write_doc() calls.

init()

Initialize the builder.

This method is called once at the beginning of the build process.

Return type:

None

get_outdated_docs()

Return an iterator of document names that need to be rebuilt.

For now, we rebuild all documents on every build.

Return type:

Iterator[str]

Returns:

Iterator of document names that are outdated

get_target_uri(docname, typ=None)

Return the target URI for a document.

Parameters:

• docname (str) – Name of the document

• typ (Optional[str]) – Type of the target (not used for Typst builder)

Return type:

str

Returns:

Target URI string

prepare_writing(docnames)

Prepare for writing the documents.

This method is called before writing begins. Writes the template file to the output directory for master documents to import.

Parameters:

docnames (Set[str]) – Set of document names to be written

Return type:

None

write(build_docnames, updated_docnames, method='update')

Override write() to preserve toctree nodes.

By default, Sphinx’s Builder.write() calls env.get_and_resolve_doctree() which expands toctree nodes into compact_paragraph with links. For Typst, we need the original toctree nodes to generate #include() directives.

This method uses env.get_doctree() instead to preserve toctree nodes.

Parameters:

• build_docnames (Optional[Set[str]]) – Document names to build (None = all)

• updated_docnames (Set[str]) – Document names that were updated

• method (str) – Build method (‘update’ or ‘all’)

Return type:

None

post_process_images(doctree)

Post-process images in the document tree.

Collects all image nodes from the document tree and tracks them in self.images dictionary for later copying to the output directory.

Parameters:

doctree (document) – Document tree to process

Return type:

None

write_doc(docname, doctree)

Write a document.

This method is called for each document that needs to be written.

Requirement 13.1: 各 reStructuredText ファイルに対応する独立した .typ ファイルを生成する

Requirement 13.12: ソースディレクトリ構造を保持して出力する

Parameters:

• docname (str) – Name of the document

• doctree (document) – Document tree to be written

Return type:

None

copy_image_files()

Copy image files to the output directory.

Iterates through all tracked images and copies them from the source directory to the output directory, preserving relative paths.

Return type:

None

finish()

Finish the build process.

This method is called once after all documents have been written. Copies image files to the output directory.

Return type:

None

class typsphinx.builder.TypstPDFBuilder(app, env)

Bases: TypstBuilder

Builder class for generating PDF output directly from Typst.

This builder extends TypstBuilder to compile generated .typ files to PDF using the typst-py package.

Requirement 9.3: TypstPDFBuilder extends TypstBuilder Requirement 9.4: Generate PDF from Typst markup

Parameters:

• app (Sphinx)

• env (BuildEnvironment)

name: str = 'typstpdf'

The builder’s name. This is the value used to select builders on the command line.

format: str = 'pdf'

The builder’s output format, or ‘’ if no document output is produced. This is commonly the file extension, e.g. “html”, though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

out_suffix = '.pdf'

write_doc(docname, doctree)

Write a document as both .typ and .pdf.

Override to generate .typ file (not .pdf) during the write phase. The .pdf will be generated in finish() by compiling the .typ file.

Parameters:

• docname (str) – Name of the document

• doctree (document) – Document tree to be written

Return type:

None

finish()

Finish the build process by compiling Typst files to PDF.

After the parent TypstBuilder has generated .typ files, this method compiles them to PDF using typst-py.

Only master documents (defined in typst_documents) are compiled to PDF. Included documents are not compiled individually.

Requirement 9.2: Execute Typst compilation within Python Requirement 9.4: Generate PDF from Typst markup

Return type:

None

PDF generation utilities using typst-py.

This module provides functionality for generating PDFs from Typst markup using the typst Python package (Requirement 9).

exception typsphinx.pdf.TypstCompilationError(message, typst_error=None, source_location=None)

Bases: Exception

Exception raised when Typst compilation fails.

This exception provides detailed information about compilation errors, including the original error from typst-py and contextual information.

Parameters:

• message (str)

• typst_error (Exception | None)

• source_location (str | None)

message

Human-readable error message

typst_error

Original error from typst compiler

source_location

Location information if available

Requirement 10.3: Error detection and handling Requirement 10.4: Error message parsing and user display

typsphinx.pdf.check_typst_available()

Check if typst package is available.

Raises:

ImportError – If typst package is not installed

Return type:

None

Requirement 9.1: Typst compiler functionality as dependency Requirement 9.7: Automatic availability of Typst compiler

Return type:

None

typsphinx.pdf.get_typst_version()

Get the version of the typst package.

Return type:

str

Returns:

Version string (e.g., “0.13.7”)

Requirement 9.7: Version information for Typst compiler

typsphinx.pdf.compile_typst_to_pdf(typst_content, root_dir=None)

Compile Typst content to PDF bytes.

Parameters:

• typst_content (str) – Typst markup content

• root_dir (Optional[str]) – Root directory for resolving includes and images

Return type:

bytes

Returns:

PDF content as bytes

Raises:

• ImportError – If typst package not available

• TypstCompilationError – If compilation fails

Requirement 9.2: Execute Typst compilation within Python environment Requirement 9.4: Generate PDF from Typst markup Requirement 10.3: Error detection and handling

Writer and Translator

Typst writer for docutils.

This module implements the TypstWriter class, which converts docutils document trees to Typst markup.

class typsphinx.writer.TypstWriter(builder)

Bases: Writer

Writer class for Typst output format.

This writer converts docutils document trees to Typst markup files.

Parameters:

builder (Any)

supported = ('typst',)

Formats this writer supports.

translate()

Translate the document tree to Typst markup.

This method creates a TypstTranslator and visits the document tree, then wraps the output with a template using TemplateEngine.

For master documents (defined in typst_documents), the full template is applied. For included documents, only the body content is output.

Return type:

None

Typst translator for docutils nodes.

This module implements the TypstTranslator class, which translates docutils nodes to Typst markup.

class typsphinx.translator.TypstTranslator(document, builder)

Bases: SphinxTranslator

Translator class that converts docutils nodes to Typst markup.

This translator visits nodes in the document tree and generates corresponding Typst markup.

Parameters:

• document (document)

• builder (Any)

astext()

Return the translated text as a string.

Return type:

str

Returns:

The translated Typst markup

add_text(text)

Add text to the output body or table cell content.

Parameters:

text (str) – The text to add

Return type:

None

visit_document(node)

Visit a document node.

Generates opening code block wrapper for unified code mode.

Parameters:

node (document) – The document node

Return type:

None

depart_document(node)

Depart a document node.

Generates closing code block wrapper for unified code mode.

Parameters:

node (document) – The document node

Return type:

None

visit_section(node)

Visit a section node.

Parameters:

node (section) – The section node

Return type:

None

depart_section(node)

Depart a section node.

Parameters:

node (section) – The section node

Return type:

None

visit_title(node)

Visit a title node.

Generates heading() function call with level parameter. Child text nodes will be wrapped in text() automatically.

Parameters:

node (title) – The title node

Return type:

None

depart_title(node)

Depart a title node.

Closes heading() function call.

Parameters:

node (title) – The title node

Return type:

None

visit_subtitle(node)

Visit a subtitle node.

Generates emph() function for subtitle (no # prefix in code mode). Child text nodes will be wrapped in text() automatically.

Parameters:

node (subtitle) – The subtitle node

Return type:

None

depart_subtitle(node)

Depart a subtitle node.

Closes emph() function.

Parameters:

node (subtitle) – The subtitle node

Return type:

None

visit_compound(node)

Visit a compound node.

Compound nodes are containers that group related content. They are often used to wrap toctree directives.

Parameters:

node (compound) – The compound node

Return type:

None

depart_compound(node)

Depart a compound node.

Parameters:

node (compound) – The compound node

Return type:

None

visit_container(node)

Visit a container node.

Handle Sphinx-generated containers, particularly literal-block-wrapper for captioned code blocks (Issue #20).

Parameters:

node (container) – The container node

Return type:

None

depart_container(node)

Depart a container node.

Parameters:

node (container) – The container node

Return type:

None

visit_paragraph(node)

Visit a paragraph node.

Wraps paragraph content in par() function for unified code mode. Code mode doesn’t auto-recognize paragraph breaks from blank lines.

Exception: Inside list items, paragraphs are not wrapped in par() to avoid syntax like “- par(text(…))” which is invalid.

Parameters:

node (paragraph) – The paragraph node

Return type:

None

depart_paragraph(node)

Depart a paragraph node.

Closes par({}) function and adds spacing.

Parameters:

node (paragraph) – The paragraph node

Return type:

None

visit_comment(node)

Visit a comment node.

Comments are skipped entirely in Typst output as they are meant for source-level documentation only.

Parameters:

node (comment) – The comment node

Raises:

nodes.SkipNode – Always raised to skip the comment

Return type:

None

depart_comment(node)

Depart a comment node.

Parameters:

node (comment) – The comment node

Return type:

None

Note

This method is not called when SkipNode is raised in visit_comment.

visit_raw(node)

Visit a raw node.

Pass through content if format is ‘typst’, otherwise skip.

Parameters:

node (raw) – The raw node

Raises:

nodes.SkipNode – When format is not ‘typst’

Return type:

None

depart_raw(node)

Depart a raw node.

Parameters:

node (raw) – The raw node

Return type:

None

Note

This method is not called when SkipNode is raised in visit_raw.

visit_Text(node)

Visit a text node.

Wraps text in text() function for unified code mode. Uses string escaping (not markup escaping).

Exception: Inside literal blocks, text is output directly without text() wrapping to preserve code content.

Parameters:

node (Text) – The text node

Return type:

None

depart_Text(node)

Depart a text node.

Parameters:

node (Text) – The text node

Return type:

None

visit_emphasis(node)

Visit an emphasis (italic) node.

Generates emph() function call. Child text nodes will be wrapped in text() automatically.

Parameters:

node (emphasis) – The emphasis node

Return type:

None

depart_emphasis(node)

Depart an emphasis (italic) node.

Closes emph({}) function call.

Parameters:

node (emphasis) – The emphasis node

Return type:

None

visit_strong(node)

Visit a strong (bold) node.

Generates strong() function call. Child text nodes will be wrapped in text() automatically.

Parameters:

node (strong) – The strong node

Return type:

None

depart_strong(node)

Depart a strong (bold) node.

Closes strong({}) function call.

Parameters:

node (strong) – The strong node

Return type:

None

visit_literal(node)

Visit a literal (inline code) node.

Generates raw() function call with backtick raw string. Uses backticks to avoid escaping issues.

Parameters:

node (literal) – The literal node

Return type:

None

depart_literal(node)

Depart a literal (inline code) node.

This is not called when SkipNode is raised in visit_literal.

Parameters:

node (literal) – The literal node

Return type:

None

visit_subscript(node)

Visit a subscript node.

Generates sub() function call. Child text nodes will be wrapped in text() automatically.

Parameters:

node (subscript) – The subscript node

Return type:

None

depart_subscript(node)

Depart a subscript node.

Closes sub() function call.

Parameters:

node (subscript) – The subscript node

Return type:

None

visit_superscript(node)

Visit a superscript node.

Generates super() function call. Child text nodes will be wrapped in text() automatically.

Parameters:

node (superscript) – The superscript node

Return type:

None

depart_superscript(node)

Depart a superscript node.

Closes super() function call.

Parameters:

node (superscript) – The superscript node

Return type:

None

visit_bullet_list(node)

Visit a bullet list node.

Outputs list( and prepares for stream-based item rendering.

Parameters:

node (bullet_list) – The bullet list node

Return type:

None

depart_bullet_list(node)

Depart a bullet list node.

Closes the list() function.

Parameters:

node (bullet_list) – The bullet list node

Return type:

None

visit_enumerated_list(node)

Visit an enumerated (numbered) list node.

Outputs enum( and prepares for stream-based item rendering.

Parameters:

node (enumerated_list) – The enumerated list node

Return type:

None

depart_enumerated_list(node)

Depart an enumerated (numbered) list node.

Closes the enum() function.

Parameters:

node (enumerated_list) – The enumerated list node

Return type:

None

visit_list_item(node)

Visit a list item node.

Adds comma separator if not first item, then prepares for item content.

Parameters:

node (list_item) – The list item node

Return type:

None

depart_list_item(node)

Depart a list item node.

Close the { } block wrapper and mark that we’re no longer in a list item.

Parameters:

node (list_item) – The list item node

Return type:

None

visit_literal_block(node)

Visit a literal block (code block) node.

Implements Task 4.2.2: codly forced usage with #codly-range() for highlighted lines Design 3.5: All code blocks use codly, with #codly-range() for highlights Requirements 7.3, 7.4: Support line numbers and highlighted lines Issue #20: Support :linenos:, :caption:, and :name: options Issue #31: Support :lineno-start: and :dedent: options

Parameters:

node (literal_block) – The literal block node

Return type:

None

depart_literal_block(node)

Depart a literal block (code block) node.

Issue #20: Handle closing figure bracket and labels.

Parameters:

node (literal_block) – The literal block node

Return type:

None

visit_definition_list(node)

Visit a definition list node.

Collects all term-definition pairs and generates terms() function in unified code mode.

Parameters:

node (definition_list) – The definition list node

Return type:

None

depart_definition_list(node)

Depart a definition list node.

Generates terms() function with all collected term-definition pairs.

Parameters:

node (definition_list) – The definition list node

Return type:

None

visit_definition_list_item(node)

Visit a definition list item node.

Parameters:

node (definition_list_item) – The definition list item node

Return type:

None

depart_definition_list_item(node)

Depart a definition list item node.

Parameters:

node (definition_list_item) – The definition list item node

Return type:

None

visit_term(node)

Visit a term (definition list term) node.

Starts buffering term content.

Parameters:

node (term) – The term node

Return type:

None

depart_term(node)

Depart a term (definition list term) node.

Saves buffered term content.

Parameters:

node (term) – The term node

Return type:

None

visit_definition(node)

Visit a definition (definition list definition) node.

Starts buffering definition content.

Parameters:

node (definition) – The definition node

Return type:

None

depart_definition(node)

Depart a definition (definition list definition) node.

Saves buffered definition content and pairs it with the term.

Parameters:

node (definition) – The definition node

Return type:

None

visit_figure(node)

Visit a figure node.

Generates figure() function call (no # prefix in code mode).

Parameters:

node (figure) – The figure node

Return type:

None

depart_figure(node)

Depart a figure node.

Parameters:

node (figure) – The figure node

Return type:

None

visit_caption(node)

Visit a caption node.

Handles captions for both figures and code blocks (Issue #20).

Parameters:

node (caption) – The caption node

Return type:

None

depart_caption(node)

Depart a caption node.

Parameters:

node (caption) – The caption node

Return type:

None

visit_table(node)

Visit a table node.

Parameters:

node (table) – The table node

Return type:

None

depart_table(node)

Depart a table node.

Parameters:

node (table) – The table node

Return type:

None

visit_tgroup(node)

Visit a tgroup (table group) node.

Parameters:

node (tgroup) – The tgroup node

Return type:

None

depart_tgroup(node)

Depart a tgroup (table group) node.

Parameters:

node (tgroup) – The tgroup node

Return type:

None

visit_colspec(node)

Visit a colspec (column specification) node.

Parameters:

node (colspec) – The colspec node

Return type:

None

depart_colspec(node)

Depart a colspec (column specification) node.

Parameters:

node (colspec) – The colspec node

Return type:

None

visit_thead(node)

Visit a thead (table header) node.

Parameters:

node (thead) – The thead node

Return type:

None

depart_thead(node)

Depart a thead (table header) node.

Parameters:

node (thead) – The thead node

Return type:

None

visit_tbody(node)

Visit a tbody (table body) node.

Parameters:

node (tbody) – The tbody node

Return type:

None

depart_tbody(node)

Depart a tbody (table body) node.

Parameters:

node (tbody) – The tbody node

Return type:

None

visit_row(node)

Visit a row (table row) node.

Parameters:

node (row) – The row node

Return type:

None

depart_row(node)

Depart a row (table row) node.

Parameters:

node (row) – The row node

Return type:

None

visit_entry(node)

Visit an entry (table cell) node.

Parameters:

node (entry) – The entry node

Return type:

None

depart_entry(node)

Depart an entry (table cell) node.

Parameters:

node (entry) – The entry node

Return type:

None

visit_block_quote(node)

Visit a block quote node.

Generates quote() function call (no # prefix in code mode).

Parameters:

node (block_quote) – The block quote node

Return type:

None

depart_block_quote(node)

Depart a block quote node.

Parameters:

node (block_quote) – The block quote node

Return type:

None

visit_attribution(node)

Visit an attribution node (quote attribution).

Parameters:

node (attribution) – The attribution node

Return type:

None

depart_attribution(node)

Depart an attribution node.

Parameters:

node (attribution) – The attribution node

Return type:

None

visit_image(node)

Visit an image node.

Generates image() function call (no # prefix in code mode). Adjusts image paths for nested documents (Issue #69).

Parameters:

node (image) – The image node

Return type:

None

depart_image(node)

Depart an image node.

Parameters:

node (image) – The image node

Return type:

None

visit_target(node)

Visit a target node (label definition).

Parameters:

node (target) – The target node

Return type:

None

depart_target(node)

Depart a target node.

Parameters:

node (target) – The target node

Return type:

None

visit_pending_xref(node)

Visit a pending_xref node (Sphinx cross-reference).

Parameters:

node (Node) – The pending_xref node

Return type:

None

depart_pending_xref(node)

Depart a pending_xref node.

Parameters:

node (Node) – The pending_xref node

Return type:

None

visit_toctree(node)

Visit a toctree node (Sphinx table of contents tree).

Requirement 13: Multi-document integration and toctree processing - Generate #include() for each entry - Apply #set heading(offset: 1) to lower heading levels - Issue #5: Fix relative paths for nested toctrees

• Calculate relative paths from current document

• Issue #7: Simplify toctree output with single content block - Generate single #[…] block containing all includes - Apply #set heading(offset: 1) once per toctree

Parameters:

node (Node) – The toctree node

Return type:

None

Notes

This method generates Typst #include() directives for each toctree entry within a single content block #[…] to apply heading offset without displaying the block delimiters in the output. This simplifies the generated Typst code and improves readability.

depart_toctree(node)

Depart a toctree node.

Parameters:

node (Node) – The toctree node

Return type:

None

visit_reference(node)

Visit a reference node (link).

Generates link() function call (no # prefix in code mode).

Parameters:

node (reference) – The reference node

Return type:

None

depart_reference(node)

Depart a reference node.

Parameters:

node (reference) – The reference node

Return type:

None

unknown_visit(node)

Handle unknown nodes during visit.

Parameters:

node (Node) – The unknown node

Return type:

None

unknown_departure(node)

Handle unknown nodes during departure.

Parameters:

node (Node) – The unknown node

Return type:

None

visit_math(node)

Visit an inline math node.

Implements Task 6.2: LaTeX math conversion (mitex) Implements Task 6.3: Labeled equations Implements Task 6.4: Typst native math support Implements Task 6.5: Math fallback functionality Requirement 4.3: Inline math should use #mi(…) format (LaTeX) Requirement 4.9: Fallback when typst_use_mitex=False Requirement 5.2: Inline math should use $…$ format (Typst native) Requirement 4.7: Labeled equations should generate <eq:label> format Design 3.3: Support both mitex and Typst native math

Parameters:

node (math) – The inline math node

Return type:

None

depart_math(node)

Depart an inline math node.

Parameters:

node (math) – The inline math node

Return type:

None

visit_math_block(node)

Visit a block math node.

Implements Task 6.2: LaTeX math conversion (mitex) Implements Task 6.3: Labeled equations Implements Task 6.4: Typst native math support Implements Task 6.5: Math fallback functionality Requirement 4.2: Block math should use #mitex(…) format (LaTeX) Requirement 4.9: Fallback when typst_use_mitex=False Requirement 5.2: Block math should use $ … $ format (Typst native) Requirement 4.7: Labeled equations should generate <eq:label> format Design 3.3: Support both mitex and Typst native math

Parameters:

node (math_block) – The block math node

Return type:

None

depart_math_block(node)

Depart a block math node.

Parameters:

node (math_block) – The block math node

Return type:

None

visit_note(node)

Visit a note admonition (converts to #info[]).

Return type:

None

Parameters:

node (note)

depart_note(node)

Depart a note admonition.

Return type:

None

Parameters:

node (note)

visit_warning(node)

Visit a warning admonition (converts to #warning[]).

Return type:

None

Parameters:

node (warning)

depart_warning(node)

Depart a warning admonition.

Return type:

None

Parameters:

node (warning)

visit_tip(node)

Visit a tip admonition (converts to #tip[]).

Return type:

None

Parameters:

node (tip)

depart_tip(node)

Depart a tip admonition.

Return type:

None

Parameters:

node (tip)

visit_important(node)

Visit an important admonition (converts to #warning(title: “Important”)[]).

Return type:

None

Parameters:

node (important)

depart_important(node)

Depart an important admonition.

Return type:

None

Parameters:

node (important)

visit_caution(node)

Visit a caution admonition (converts to #warning[]).

Return type:

None

Parameters:

node (caution)

depart_caution(node)

Depart a caution admonition.

Return type:

None

Parameters:

node (caution)

visit_seealso(node)

Visit a seealso admonition (converts to #info(title: “See Also”)[]).

Return type:

None

Parameters:

node (seealso)

depart_seealso(node)

Depart a seealso admonition.

Return type:

None

Parameters:

node (seealso)

visit_inline(node)

Visit an inline node.

Inline nodes are generic containers for inline content. They are often used for cross-references with specific CSS classes.

Task 7.4: Handle inline nodes, especially those with ‘xref’ class Requirement 3.1: Cross-references and links

Return type:

None

Parameters:

node (inline)

depart_inline(node)

Depart an inline node.

Return type:

None

Parameters:

node (inline)

visit_index(node)

Visit an index node.

Index entries are skipped in Typst/PDF output as we don’t generate indices.

Return type:

None

Parameters:

node (index)

depart_index(node)

Depart an index node.

Return type:

None

Parameters:

node (index)

visit_desc(node)

Visit a desc node (API description container).

Desc nodes contain API descriptions (classes, functions, methods, etc.).

Return type:

None

Parameters:

node (desc)

depart_desc(node)

Depart a desc node.

Add spacing after API description blocks.

Return type:

None

Parameters:

node (desc)

visit_desc_signature(node)

Visit a desc_signature node (API element signature).

Signatures are rendered in bold using strong({}) wrapper.

Return type:

None

Parameters:

node (desc_signature)

depart_desc_signature(node)

Depart a desc_signature node.

Return type:

None

Parameters:

node (desc_signature)

visit_desc_content(node)

Visit a desc_content node (API description content).

Return type:

None

Parameters:

node (desc_content)

depart_desc_content(node)

Depart a desc_content node.

Return type:

None

Parameters:

node (desc_content)

visit_desc_annotation(node)

Visit a desc_annotation node (type annotations like ‘class’, ‘async’, etc.).

Return type:

None

Parameters:

node (desc_annotation)

depart_desc_annotation(node)

Depart a desc_annotation node.

Space after annotation is handled by desc_sig_space node.

Return type:

None

Parameters:

node (desc_annotation)

visit_desc_addname(node)

Visit a desc_addname node (module name prefix).

Return type:

None

Parameters:

node (desc_addname)

depart_desc_addname(node)

Depart a desc_addname node.

Return type:

None

Parameters:

node (desc_addname)

visit_desc_name(node)

Visit a desc_name node (function/class name).

Return type:

None

Parameters:

node (desc_name)

depart_desc_name(node)

Depart a desc_name node.

Return type:

None

Parameters:

node (desc_name)

visit_desc_parameterlist(node)

Visit a desc_parameterlist node (parameter list container).

Parameters are concatenated with + inside text parentheses.

Return type:

None

Parameters:

node (desc_parameterlist)

depart_desc_parameterlist(node)

Depart a desc_parameterlist node.

Return type:

None

Parameters:

node (desc_parameterlist)

visit_desc_parameter(node)

Visit a desc_parameter node (individual parameter).

Return type:

None

Parameters:

node (desc_parameter)

depart_desc_parameter(node)

Depart a desc_parameter node.

Add comma + space between parameters if not last.

Return type:

None

Parameters:

node (desc_parameter)

visit_field_list(node)

Visit a field_list node (structured fields like Parameters, Returns).

Return type:

None

Parameters:

node (field_list)

depart_field_list(node)

Depart a field_list node.

Add spacing after field lists.

Return type:

None

Parameters:

node (field_list)

visit_field(node)

Visit a field node (individual field in a field list).

Return type:

None

Parameters:

node (field)

depart_field(node)

Depart a field node.

Return type:

None

Parameters:

node (field)

visit_field_name(node)

Visit a field_name node (field name like ‘Parameters’, ‘Returns’).

Field names are rendered in bold with a colon (no # prefix in code mode).

Return type:

None

Parameters:

node (field_name)

depart_field_name(node)

Depart a field_name node.

Return type:

None

Parameters:

node (field_name)

visit_field_body(node)

Visit a field_body node (field content).

Return type:

None

Parameters:

node (field_body)

depart_field_body(node)

Depart a field_body node.

Add newline after field body.

Return type:

None

Parameters:

node (field_body)

visit_rubric(node)

Visit a rubric node (section subheading).

Rubrics are rendered as subsection headings using strong({}) wrapper.

Return type:

None

Parameters:

node (rubric)

depart_rubric(node)

Depart a rubric node.

Return type:

None

Parameters:

node (rubric)

visit_title_reference(node)

Visit a title_reference node (reference to a title).

Title references are rendered in emphasis using emph({}) wrapper.

Return type:

None

Parameters:

node (title_reference)

depart_title_reference(node)

Depart a title_reference node.

Return type:

None

Parameters:

node (title_reference)

visit_desc_sig_keyword(node)

Visit a desc_sig_keyword node (keywords in signatures like ‘class’, ‘def’).

Return type:

None

Parameters:

node (desc_sig_keyword)

depart_desc_sig_keyword(node)

Depart a desc_sig_keyword node.

Return type:

None

Parameters:

node (desc_sig_keyword)

visit_desc_sig_space(node)

Visit a desc_sig_space node (whitespace in signatures).

Return type:

None

Parameters:

node (desc_sig_space)

depart_desc_sig_space(node)

Depart a desc_sig_space node.

Return type:

None

Parameters:

node (desc_sig_space)

visit_desc_sig_name(node)

Visit a desc_sig_name node (names in signatures).

Return type:

None

Parameters:

node (desc_sig_name)

depart_desc_sig_name(node)

Depart a desc_sig_name node.

Return type:

None

Parameters:

node (desc_sig_name)

visit_desc_sig_punctuation(node)

Visit a desc_sig_punctuation node (punctuation in signatures like ‘:’, ‘=’).

Return type:

None

Parameters:

node (desc_sig_punctuation)

depart_desc_sig_punctuation(node)

Depart a desc_sig_punctuation node.

Return type:

None

Parameters:

node (desc_sig_punctuation)

visit_desc_sig_operator(node)

Visit a desc_sig_operator node (operators in signatures).

Return type:

None

Parameters:

node (desc_sig_operator)

depart_desc_sig_operator(node)

Depart a desc_sig_operator node.

Return type:

None

Parameters:

node (desc_sig_operator)

visit_literal_strong(node)

Visit a literal_strong node (bold literal text in field lists).

Return type:

None

Parameters:

node (inline)

depart_literal_strong(node)

Depart a literal_strong node.

Return type:

None

Parameters:

node (inline)

visit_literal_emphasis(node)

Visit a literal_emphasis node (emphasized literal text in field lists).

Return type:

None

Parameters:

node (inline)

depart_literal_emphasis(node)

Depart a literal_emphasis node.

Return type:

None

Parameters:

node (inline)

Template Engine

Template engine for Typst document generation.

This module implements template loading, parameter mapping, and rendering for Typst documents (Requirement 8).

class typsphinx.template_engine.TemplateEngine(template_path=None, template_name=None, search_paths=None, parameter_mapping=None, typst_package=None, typst_template_function=None, typst_package_imports=None, typst_authors=None, typst_author_params=None)

Bases: object

Manages Typst templates for document generation.

Responsibilities: - Load default or custom Typst templates - Search templates in multiple directories with priority - Provide fallback to default template when custom template not found - Map Sphinx metadata to template parameters - Render final Typst document with template and content

Requirement 8.1: Default Typst template included in package Requirement 8.2: Support custom template specification Requirement 8.7: Priority search in user project directory Requirement 8.9: Fallback to default template with warning

Parameters:

• template_path (str | None)

• template_name (str | None)

• search_paths (List[str] | None)

• parameter_mapping (Dict[str, str] | None)

• typst_package (str | None)

• typst_template_function (Any | None)

• typst_package_imports (List[str] | None)

• typst_authors (Dict[str, Dict[str, Any]] | None)

• typst_author_params (Dict[str, Dict[str, Any]] | None)

DEFAULT_PARAMETER_MAPPING = {'author': 'authors', 'project': 'title', 'release': 'date'}

get_default_template_path()

Get the path to the default template bundled with the package.

Return type:

str

Returns:

Absolute path to default template file

load_template()

Load Typst template with priority order: 1. Explicit template_path if provided 2. Search for template_name in search_paths (first match wins) 3. Default template bundled with package

Return type:

str

Returns:

Template content as string

Requirement 8.1: Load default template Requirement 8.2: Load custom template Requirement 8.7: Search in user project directory Requirement 8.9: Fallback to default with warning

map_parameters(sphinx_metadata)

Map Sphinx metadata to template parameters.

Parameters:

sphinx_metadata (Dict[str, Any]) – Dictionary of Sphinx configuration metadata (project, author, release, etc.)

Return type:

Dict[str, Any]

Returns:

Dictionary of template parameters ready to pass to template

Requirement 8.3: Pass Sphinx metadata to template Requirement 8.4: Support different parameter names Requirement 8.5: Standard metadata name transformation Requirement 8.8: Convert to arrays and complex structures

generate_package_import()

Generate Typst package import statement.

Return type:

str

Returns:

Import statement string, or empty string if no package specified

Requirement 8.6: Typst Universe external template packages

extract_toctree_options(doctree)

Extract toctree options from doctree for template parameters.

Parameters:

doctree (Any) – Docutils document tree

Return type:

Dict[str, Any]

Returns:

Dictionary of toctree options for template

Requirement 8.12: toctree options passed as template parameters Requirement 8.13: template reflects toctree options in #outline() Requirement 13.8: #outline() managed at template level Requirement 13.9: toctree options mapped to template parameters

get_template_content()

Get the template content for writing to a separate file.

Return type:

str

Returns:

Template content as string

This is used when templates are written as separate files instead of being inlined in the main document.

render(params, body, template_file=None)

Render final Typst document with template and body.

Parameters:

• params (Dict[str, Any]) – Template parameters (title, authors, etc.)

• body (str) – Document body content (Typst markup)

• template_file (str) – Path to template file for import (relative to output dir). If None, template is inlined (old behavior). If specified, template is imported from file.

Return type:

str

Returns:

Complete Typst document string

Requirement 8.2: Use custom template Requirement 8.10: Pass document settings to template Requirement 8.14: #outline() in template, not body

Configuration

Configuration values are registered in the main __init__.py module.

Available Configuration Values

Name	Description	Default
typst_documents	List of documents to build	[]
typst_template	Path to custom template file	None
typst_template_function	Template function name or dict	None
typst_package	Typst Universe package	None
typst_authors	Detailed author information	None
typst_use_mitex	Use mitex for LaTeX math	True
typst_use_codly	Use codly for code highlighting	True
typst_code_line_numbers	Show line numbers in code blocks	True
typst_papersize	Paper size (e.g., “a4”, “us-letter”)	"a4"
typst_fontsize	Base font size	"11pt"

See Configuration for detailed usage of each option.

Indices and Tables

• Index

• Module Index