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)

ベースクラス: 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.

パラメータ:

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

戻り値の型:

None

get_outdated_docs()

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

For now, we rebuild all documents on every build.

戻り値の型:

Iterator[str]

戻り値:

Iterator of document names that are outdated

get_target_uri(docname, typ=None)

Return the target URI for a document.

パラメータ:

• docname (str) -- Name of the document

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

戻り値の型:

str

戻り値:

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.

パラメータ:

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

戻り値の型:

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.

パラメータ:

• 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')

戻り値の型:

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.

パラメータ:

doctree (document) -- Document tree to process

戻り値の型:

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: ソースディレクトリ構造を保持して出力する

パラメータ:

• docname (str) -- Name of the document

• doctree (document) -- Document tree to be written

戻り値の型:

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.

戻り値の型:

None

copy_template_assets()

Copy template-associated assets to the output directory.

When using custom Typst templates via typst_template configuration, this method copies assets (fonts, images, logos, etc.) referenced by the template to the output directory.

Behavior: - If typst_template_assets is configured, copies only specified files/directories - If typst_template_assets is None (default), automatically copies entire template directory - If typst_template_assets is empty list, disables automatic copying - Skips .typ files to avoid duplicating template file (already handled by _write_template_file)

This follows the same pattern as copy_image_files() from Issue #38.

戻り値の型:

None

finish()

Finish the build process.

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

戻り値の型:

None

class typsphinx.builder.TypstPDFBuilder(app, env)

ベースクラス: 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

パラメータ:

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

パラメータ:

• docname (str) -- Name of the document

• doctree (document) -- Document tree to be written

戻り値の型:

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

戻り値の型:

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)

ベースクラス: 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.

パラメータ:

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

例外:

ImportError -- If typst package is not installed

戻り値の型:

None

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

戻り値の型:

None

typsphinx.pdf.get_typst_version()

Get the version of the typst package.

戻り値の型:

str

戻り値:

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.

パラメータ:

• typst_content (str) -- Typst markup content

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

戻り値の型:

bytes

戻り値:

PDF content as bytes

例外:

• 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)

ベースクラス: Writer

Writer class for Typst output format.

This writer converts docutils document trees to Typst markup files.

パラメータ:

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.

戻り値の型:

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)

ベースクラス: SphinxTranslator

Translator class that converts docutils nodes to Typst markup.

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

パラメータ:

• document (document)

• builder (Any)

astext()

Return the translated text as a string.

戻り値の型:

str

戻り値:

The translated Typst markup

add_text(text)

Add text to the output body or table cell content.

パラメータ:

text (str) -- The text to add

戻り値の型:

None

visit_document(node)

Visit a document node.

Generates opening code block wrapper for unified code mode.

パラメータ:

node (document) -- The document node

戻り値の型:

None

depart_document(node)

Depart a document node.

Generates closing code block wrapper for unified code mode.

パラメータ:

node (document) -- The document node

戻り値の型:

None

visit_section(node)

Visit a section node.

パラメータ:

node (section) -- The section node

戻り値の型:

None

depart_section(node)

Depart a section node.

パラメータ:

node (section) -- The section node

戻り値の型:

None

visit_title(node)

Visit a title node.

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

パラメータ:

node (title) -- The title node

戻り値の型:

None

depart_title(node)

Depart a title node.

Closes heading() function call.

パラメータ:

node (title) -- The title node

戻り値の型:

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.

パラメータ:

node (subtitle) -- The subtitle node

戻り値の型:

None

depart_subtitle(node)

Depart a subtitle node.

Closes emph() function.

パラメータ:

node (subtitle) -- The subtitle node

戻り値の型:

None

visit_compound(node)

Visit a compound node.

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

パラメータ:

node (compound) -- The compound node

戻り値の型:

None

depart_compound(node)

Depart a compound node.

パラメータ:

node (compound) -- The compound node

戻り値の型:

None

visit_container(node)

Visit a container node.

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

パラメータ:

node (container) -- The container node

戻り値の型:

None

depart_container(node)

Depart a container node.

パラメータ:

node (container) -- The container node

戻り値の型:

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.

パラメータ:

node (paragraph) -- The paragraph node

戻り値の型:

None

depart_paragraph(node)

Depart a paragraph node.

Closes par({}) function and adds spacing.

パラメータ:

node (paragraph) -- The paragraph node

戻り値の型:

None

visit_comment(node)

Visit a comment node.

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

パラメータ:

node (comment) -- The comment node

例外:

nodes.SkipNode -- Always raised to skip the comment

戻り値の型:

None

depart_comment(node)

Depart a comment node.

パラメータ:

node (comment) -- The comment node

戻り値の型:

None

注釈

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.

パラメータ:

node (raw) -- The raw node

例外:

nodes.SkipNode -- When format is not 'typst'

戻り値の型:

None

depart_raw(node)

Depart a raw node.

パラメータ:

node (raw) -- The raw node

戻り値の型:

None

注釈

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.

パラメータ:

node (Text) -- The text node

戻り値の型:

None

depart_Text(node)

Depart a text node.

パラメータ:

node (Text) -- The text node

戻り値の型:

None

visit_emphasis(node)

Visit an emphasis (italic) node.

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

パラメータ:

node (emphasis) -- The emphasis node

戻り値の型:

None

depart_emphasis(node)

Depart an emphasis (italic) node.

Closes emph({}) function call.

パラメータ:

node (emphasis) -- The emphasis node

戻り値の型:

None

visit_strong(node)

Visit a strong (bold) node.

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

パラメータ:

node (strong) -- The strong node

戻り値の型:

None

depart_strong(node)

Depart a strong (bold) node.

Closes strong({}) function call.

パラメータ:

node (strong) -- The strong node

戻り値の型:

None

visit_literal(node)

Visit a literal (inline code) node.

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

パラメータ:

node (literal) -- The literal node

戻り値の型:

None

depart_literal(node)

Depart a literal (inline code) node.

This is not called when SkipNode is raised in visit_literal.

パラメータ:

node (literal) -- The literal node

戻り値の型:

None

visit_subscript(node)

Visit a subscript node.

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

パラメータ:

node (subscript) -- The subscript node

戻り値の型:

None

depart_subscript(node)

Depart a subscript node.

Closes sub() function call.

パラメータ:

node (subscript) -- The subscript node

戻り値の型:

None

visit_superscript(node)

Visit a superscript node.

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

パラメータ:

node (superscript) -- The superscript node

戻り値の型:

None

depart_superscript(node)

Depart a superscript node.

Closes super() function call.

パラメータ:

node (superscript) -- The superscript node

戻り値の型:

None

visit_bullet_list(node)

Visit a bullet list node.

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

パラメータ:

node (bullet_list) -- The bullet list node

戻り値の型:

None

depart_bullet_list(node)

Depart a bullet list node.

Closes the list() function.

パラメータ:

node (bullet_list) -- The bullet list node

戻り値の型:

None

visit_enumerated_list(node)

Visit an enumerated (numbered) list node.

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

パラメータ:

node (enumerated_list) -- The enumerated list node

戻り値の型:

None

depart_enumerated_list(node)

Depart an enumerated (numbered) list node.

Closes the enum() function.

パラメータ:

node (enumerated_list) -- The enumerated list node

戻り値の型:

None

visit_list_item(node)

Visit a list item node.

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

パラメータ:

node (list_item) -- The list item node

戻り値の型:

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.

パラメータ:

node (list_item) -- The list item node

戻り値の型:

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

パラメータ:

node (literal_block) -- The literal block node

戻り値の型:

None

depart_literal_block(node)

Depart a literal block (code block) node.

Issue #20: Handle closing figure bracket and labels.

パラメータ:

node (literal_block) -- The literal block node

戻り値の型:

None

visit_definition_list(node)

Visit a definition list node.

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

パラメータ:

node (definition_list) -- The definition list node

戻り値の型:

None

depart_definition_list(node)

Depart a definition list node.

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

パラメータ:

node (definition_list) -- The definition list node

戻り値の型:

None

visit_definition_list_item(node)

Visit a definition list item node.

パラメータ:

node (definition_list_item) -- The definition list item node

戻り値の型:

None

depart_definition_list_item(node)

Depart a definition list item node.

パラメータ:

node (definition_list_item) -- The definition list item node

戻り値の型:

None

visit_term(node)

Visit a term (definition list term) node.

Starts buffering term content.

パラメータ:

node (term) -- The term node

戻り値の型:

None

depart_term(node)

Depart a term (definition list term) node.

Saves buffered term content.

パラメータ:

node (term) -- The term node

戻り値の型:

None

visit_definition(node)

Visit a definition (definition list definition) node.

Starts buffering definition content.

パラメータ:

node (definition) -- The definition node

戻り値の型:

None

depart_definition(node)

Depart a definition (definition list definition) node.

Saves buffered definition content and pairs it with the term.

パラメータ:

node (definition) -- The definition node

戻り値の型:

None

visit_figure(node)

Visit a figure node.

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

パラメータ:

node (figure) -- The figure node

戻り値の型:

None

depart_figure(node)

Depart a figure node.

パラメータ:

node (figure) -- The figure node

戻り値の型:

None

visit_caption(node)

Visit a caption node.

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

パラメータ:

node (caption) -- The caption node

戻り値の型:

None

depart_caption(node)

Depart a caption node.

パラメータ:

node (caption) -- The caption node

戻り値の型:

None

visit_table(node)

Visit a table node.

パラメータ:

node (table) -- The table node

戻り値の型:

None

depart_table(node)

Depart a table node.

パラメータ:

node (table) -- The table node

戻り値の型:

None

visit_tgroup(node)

Visit a tgroup (table group) node.

パラメータ:

node (tgroup) -- The tgroup node

戻り値の型:

None

depart_tgroup(node)

Depart a tgroup (table group) node.

パラメータ:

node (tgroup) -- The tgroup node

戻り値の型:

None

visit_colspec(node)

Visit a colspec (column specification) node.

パラメータ:

node (colspec) -- The colspec node

戻り値の型:

None

depart_colspec(node)

Depart a colspec (column specification) node.

パラメータ:

node (colspec) -- The colspec node

戻り値の型:

None

visit_thead(node)

Visit a thead (table header) node.

パラメータ:

node (thead) -- The thead node

戻り値の型:

None

depart_thead(node)

Depart a thead (table header) node.

パラメータ:

node (thead) -- The thead node

戻り値の型:

None

visit_tbody(node)

Visit a tbody (table body) node.

パラメータ:

node (tbody) -- The tbody node

戻り値の型:

None

depart_tbody(node)

Depart a tbody (table body) node.

パラメータ:

node (tbody) -- The tbody node

戻り値の型:

None

visit_row(node)

Visit a row (table row) node.

パラメータ:

node (row) -- The row node

戻り値の型:

None

depart_row(node)

Depart a row (table row) node.

パラメータ:

node (row) -- The row node

戻り値の型:

None

visit_entry(node)

Visit an entry (table cell) node.

パラメータ:

node (entry) -- The entry node

戻り値の型:

None

depart_entry(node)

Depart an entry (table cell) node.

パラメータ:

node (entry) -- The entry node

戻り値の型:

None

visit_block_quote(node)

Visit a block quote node.

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

パラメータ:

node (block_quote) -- The block quote node

戻り値の型:

None

depart_block_quote(node)

Depart a block quote node.

パラメータ:

node (block_quote) -- The block quote node

戻り値の型:

None

visit_attribution(node)

Visit an attribution node (quote attribution).

パラメータ:

node (attribution) -- The attribution node

戻り値の型:

None

depart_attribution(node)

Depart an attribution node.

パラメータ:

node (attribution) -- The attribution node

戻り値の型:

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

パラメータ:

node (image) -- The image node

戻り値の型:

None

depart_image(node)

Depart an image node.

パラメータ:

node (image) -- The image node

戻り値の型:

None

visit_target(node)

Visit a target node (label definition).

パラメータ:

node (target) -- The target node

戻り値の型:

None

depart_target(node)

Depart a target node.

パラメータ:

node (target) -- The target node

戻り値の型:

None

visit_pending_xref(node)

Visit a pending_xref node (Sphinx cross-reference).

パラメータ:

node (Node) -- The pending_xref node

戻り値の型:

None

depart_pending_xref(node)

Depart a pending_xref node.

パラメータ:

node (Node) -- The pending_xref node

戻り値の型:

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

パラメータ:

node (Node) -- The toctree node

戻り値の型:

None

メモ

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.

パラメータ:

node (Node) -- The toctree node

戻り値の型:

None

visit_reference(node)

Visit a reference node (link).

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

パラメータ:

node (reference) -- The reference node

戻り値の型:

None

depart_reference(node)

Depart a reference node.

パラメータ:

node (reference) -- The reference node

戻り値の型:

None

unknown_visit(node)

Handle unknown nodes during visit.

パラメータ:

node (Node) -- The unknown node

戻り値の型:

None

unknown_departure(node)

Handle unknown nodes during departure.

パラメータ:

node (Node) -- The unknown node

戻り値の型:

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

パラメータ:

node (math) -- The inline math node

戻り値の型:

None

depart_math(node)

Depart an inline math node.

パラメータ:

node (math) -- The inline math node

戻り値の型:

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

パラメータ:

node (math_block) -- The block math node

戻り値の型:

None

depart_math_block(node)

Depart a block math node.

パラメータ:

node (math_block) -- The block math node

戻り値の型:

None

visit_note(node)

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

戻り値の型:

None

パラメータ:

node (note)

depart_note(node)

Depart a note admonition.

戻り値の型:

None

パラメータ:

node (note)

visit_warning(node)

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

戻り値の型:

None

パラメータ:

node (warning)

depart_warning(node)

Depart a warning admonition.

戻り値の型:

None

パラメータ:

node (warning)

visit_tip(node)

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

戻り値の型:

None

パラメータ:

node (tip)

depart_tip(node)

Depart a tip admonition.

戻り値の型:

None

パラメータ:

node (tip)

visit_important(node)

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

戻り値の型:

None

パラメータ:

node (important)

depart_important(node)

Depart an important admonition.

戻り値の型:

None

パラメータ:

node (important)

visit_caution(node)

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

戻り値の型:

None

パラメータ:

node (caution)

depart_caution(node)

Depart a caution admonition.

戻り値の型:

None

パラメータ:

node (caution)

visit_seealso(node)

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

戻り値の型:

None

パラメータ:

node (seealso)

depart_seealso(node)

Depart a seealso admonition.

戻り値の型:

None

パラメータ:

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

戻り値の型:

None

パラメータ:

node (inline)

depart_inline(node)

Depart an inline node.

戻り値の型:

None

パラメータ:

node (inline)

visit_index(node)

Visit an index node.

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

戻り値の型:

None

パラメータ:

node (index)

depart_index(node)

Depart an index node.

戻り値の型:

None

パラメータ:

node (index)

visit_desc(node)

Visit a desc node (API description container).

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

戻り値の型:

None

パラメータ:

node (desc)

depart_desc(node)

Depart a desc node.

Add spacing after API description blocks.

戻り値の型:

None

パラメータ:

node (desc)

visit_desc_signature(node)

Visit a desc_signature node (API element signature).

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

戻り値の型:

None

パラメータ:

node (desc_signature)

depart_desc_signature(node)

Depart a desc_signature node.

戻り値の型:

None

パラメータ:

node (desc_signature)

visit_desc_content(node)

Visit a desc_content node (API description content).

戻り値の型:

None

パラメータ:

node (desc_content)

depart_desc_content(node)

Depart a desc_content node.

戻り値の型:

None

パラメータ:

node (desc_content)

visit_desc_annotation(node)

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

戻り値の型:

None

パラメータ:

node (desc_annotation)

depart_desc_annotation(node)

Depart a desc_annotation node.

Space after annotation is handled by desc_sig_space node.

戻り値の型:

None

パラメータ:

node (desc_annotation)

visit_desc_addname(node)

Visit a desc_addname node (module name prefix).

戻り値の型:

None

パラメータ:

node (desc_addname)

depart_desc_addname(node)

Depart a desc_addname node.

戻り値の型:

None

パラメータ:

node (desc_addname)

visit_desc_name(node)

Visit a desc_name node (function/class name).

戻り値の型:

None

パラメータ:

node (desc_name)

depart_desc_name(node)

Depart a desc_name node.

戻り値の型:

None

パラメータ:

node (desc_name)

visit_desc_parameterlist(node)

Visit a desc_parameterlist node (parameter list container).

Parameters are concatenated with + inside text parentheses.

戻り値の型:

None

パラメータ:

node (desc_parameterlist)

depart_desc_parameterlist(node)

Depart a desc_parameterlist node.

戻り値の型:

None

パラメータ:

node (desc_parameterlist)

visit_desc_parameter(node)

Visit a desc_parameter node (individual parameter).

戻り値の型:

None

パラメータ:

node (desc_parameter)

depart_desc_parameter(node)

Depart a desc_parameter node.

Add comma + space between parameters if not last.

戻り値の型:

None

パラメータ:

node (desc_parameter)

visit_field_list(node)

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

戻り値の型:

None

パラメータ:

node (field_list)

depart_field_list(node)

Depart a field_list node.

Add spacing after field lists.

戻り値の型:

None

パラメータ:

node (field_list)

visit_field(node)

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

戻り値の型:

None

パラメータ:

node (field)

depart_field(node)

Depart a field node.

戻り値の型:

None

パラメータ:

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

戻り値の型:

None

パラメータ:

node (field_name)

depart_field_name(node)

Depart a field_name node.

戻り値の型:

None

パラメータ:

node (field_name)

visit_field_body(node)

Visit a field_body node (field content).

戻り値の型:

None

パラメータ:

node (field_body)

depart_field_body(node)

Depart a field_body node.

Add newline after field body.

戻り値の型:

None

パラメータ:

node (field_body)

visit_rubric(node)

Visit a rubric node (section subheading).

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

戻り値の型:

None

パラメータ:

node (rubric)

depart_rubric(node)

Depart a rubric node.

戻り値の型:

None

パラメータ:

node (rubric)

visit_title_reference(node)

Visit a title_reference node (reference to a title).

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

戻り値の型:

None

パラメータ:

node (title_reference)

depart_title_reference(node)

Depart a title_reference node.

戻り値の型:

None

パラメータ:

node (title_reference)

visit_desc_sig_keyword(node)

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

戻り値の型:

None

パラメータ:

node (desc_sig_keyword)

depart_desc_sig_keyword(node)

Depart a desc_sig_keyword node.

戻り値の型:

None

パラメータ:

node (desc_sig_keyword)

visit_desc_sig_space(node)

Visit a desc_sig_space node (whitespace in signatures).

戻り値の型:

None

パラメータ:

node (desc_sig_space)

depart_desc_sig_space(node)

Depart a desc_sig_space node.

戻り値の型:

None

パラメータ:

node (desc_sig_space)

visit_desc_sig_name(node)

Visit a desc_sig_name node (names in signatures).

戻り値の型:

None

パラメータ:

node (desc_sig_name)

depart_desc_sig_name(node)

Depart a desc_sig_name node.

戻り値の型:

None

パラメータ:

node (desc_sig_name)

visit_desc_sig_punctuation(node)

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

戻り値の型:

None

パラメータ:

node (desc_sig_punctuation)

depart_desc_sig_punctuation(node)

Depart a desc_sig_punctuation node.

戻り値の型:

None

パラメータ:

node (desc_sig_punctuation)

visit_desc_sig_operator(node)

Visit a desc_sig_operator node (operators in signatures).

戻り値の型:

None

パラメータ:

node (desc_sig_operator)

depart_desc_sig_operator(node)

Depart a desc_sig_operator node.

戻り値の型:

None

パラメータ:

node (desc_sig_operator)

visit_literal_strong(node)

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

戻り値の型:

None

パラメータ:

node (inline)

depart_literal_strong(node)

Depart a literal_strong node.

戻り値の型:

None

パラメータ:

node (inline)

visit_literal_emphasis(node)

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

戻り値の型:

None

パラメータ:

node (inline)

depart_literal_emphasis(node)

Depart a literal_emphasis node.

戻り値の型:

None

パラメータ:

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)

ベースクラス: 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

パラメータ:

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

戻り値の型:

str

戻り値:

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

戻り値の型:

str

戻り値:

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.

パラメータ:

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

戻り値の型:

Dict[str, Any]

戻り値:

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.

戻り値の型:

str

戻り値:

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.

パラメータ:

doctree (Any) -- Docutils document tree

戻り値の型:

Dict[str, Any]

戻り値:

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.

戻り値の型:

str

戻り値:

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.

パラメータ:

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

戻り値の型:

str

戻り値:

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

• 索引

• モジュール索引