myst_parser.parsers.docutils_

MyST Markdown parser for docutils.

1.  Module Contents

1.1.  Classes

Unset	A sentinel class for unset settings.
Parser	Docutils parser for Markedly Structured Text (MyST).
SimpleTranslator
SimpleWriter

1.2.  Functions

attr_to_optparse_option	Convert an MdParserConfig attribute into a Docutils setting tuple.
create_myst_settings_spec	Return a list of Docutils setting for the docutils MyST section.
create_myst_config	Create a configuration instance from the given settings.
cli_html	Cmdline entrypoint for converting MyST to HTML.
cli_html5	Cmdline entrypoint for converting MyST to HTML5.
cli_html5_demo	Cmdline entrypoint for converting MyST to simple HTML5 demonstrations.
to_html5_demo	Convert a MyST string to HTML5.
cli_latex	Cmdline entrypoint for converting MyST to LaTeX.
cli_xml	Cmdline entrypoint for converting MyST to XML.
cli_pseudoxml	Cmdline entrypoint for converting MyST to pseudo-XML.
visit_rubric_html	Override the default HTML visit method for rubric nodes.
depart_rubric_html	Override the default HTML visit method for rubric nodes.
visit_container_html	Override the default HTML visit method for container nodes.
depart_container_html	Override the default HTML depart method for container nodes.

1.3.  Data

DOCUTILS_UNSET

Sentinel for arguments not set through docutils.conf.

1.4.  API

class myst_parser.parsers.docutils_.Unset

A sentinel class for unset settings.

myst_parser.parsers.docutils_.DOCUTILS_UNSET = 'Unset(...)'

Sentinel for arguments not set through docutils.conf.

myst_parser.parsers.docutils_.attr_to_optparse_option(attribute: dataclasses.Field, default: Any, prefix: str = 'myst_') → tuple[str, list[str], dict[str, Any]]

Convert an MdParserConfig attribute into a Docutils setting tuple.

返回:

A tuple of (help string, option flags, optparse kwargs).

myst_parser.parsers.docutils_.create_myst_settings_spec(config_cls=MdParserConfig, prefix: str = 'myst_')

Return a list of Docutils setting for the docutils MyST section.

myst_parser.parsers.docutils_.create_myst_config(settings: docutils.frontend.Values, config_cls=MdParserConfig, prefix: str = 'myst_')

Create a configuration instance from the given settings.

class myst_parser.parsers.docutils_.Parser(rfc2822=False, inliner=None)

Bases: docutils.parsers.rst.Parser

Docutils parser for Markedly Structured Text (MyST).

Initialization

supported: tuple[str, ...] = ('md', 'markdown', 'myst')

Aliases this parser supports.

settings_spec = ('MyST options', None)

Runtime settings specification.

config_section = 'myst parser'

config_section_dependencies = ('parsers',)

translate_section_name = None

get_transforms()

parse(inputstring: str, document: docutils.nodes.document) → None

Parse source text.

参数:

• inputstring -- The source string to parse

• document -- The root docutils node to add AST elements to

class myst_parser.parsers.docutils_.SimpleTranslator(document)

Bases: docutils.writers.html5_polyglot.HTMLTranslator

stylesheet_call(*args, **kwargs)

class myst_parser.parsers.docutils_.SimpleWriter

Bases: docutils.writers.html5_polyglot.Writer

settings_spec = 'filter_settings_spec(...)'

apply_template()

myst_parser.parsers.docutils_.cli_html(argv: list[str] | None = None) → None

Cmdline entrypoint for converting MyST to HTML.

myst_parser.parsers.docutils_.cli_html5(argv: list[str] | None = None)

Cmdline entrypoint for converting MyST to HTML5.

myst_parser.parsers.docutils_.cli_html5_demo(argv: list[str] | None = None)

Cmdline entrypoint for converting MyST to simple HTML5 demonstrations.

This is a special case of the HTML5 writer, that only outputs the body of the document.

myst_parser.parsers.docutils_.to_html5_demo(inputstring: str, **kwargs) → str

Convert a MyST string to HTML5.

myst_parser.parsers.docutils_.cli_latex(argv: list[str] | None = None)

Cmdline entrypoint for converting MyST to LaTeX.

myst_parser.parsers.docutils_.cli_xml(argv: list[str] | None = None)

Cmdline entrypoint for converting MyST to XML.

myst_parser.parsers.docutils_.cli_pseudoxml(argv: list[str] | None = None)

Cmdline entrypoint for converting MyST to pseudo-XML.

myst_parser.parsers.docutils_.visit_rubric_html(self, node)

Override the default HTML visit method for rubric nodes.

docutils structures a document, based on the headings, into nested sections:

# h1
## h2
### h3

<section>
    <title>
        h1
    <section>
        <title>
            h2
        <section>
            <title>
                h3

This means that it is not possible to have "standard" headings nested inside other components, such as blockquotes, because it would break the structure:

# h1
> ## h2
### h3

<section>
    <title>
        h1
    <blockquote>
        <section>
            <title>
                h2
    <section>
        <title>
            h3

we work around this shortcoming, in DocutilsRenderer.render_heading, by identifying if a heading is inside another component and instead outputting it as a "non-structural" rubric node, and capture the level:

<section>
    <title>
        h1
    <blockquote>
        <rubric level=2>
            h2
    <section>
        <title>
            h3

However, docutils natively just outputs rubrics as <p> tags, and does not "honor" the heading level. So here we override the visit/depart methods to output the correct <h> element

myst_parser.parsers.docutils_.depart_rubric_html(self, node)

Override the default HTML visit method for rubric nodes.

See explanation in visit_rubric_html

myst_parser.parsers.docutils_.visit_container_html(self, node: docutils.nodes.Node)

Override the default HTML visit method for container nodes.

to remove the "container" class for divs this avoids CSS clashes with the bootstrap theme

myst_parser.parsers.docutils_.depart_container_html(self, node: docutils.nodes.Node)

Override the default HTML depart method for container nodes.

See explanation in visit_container_html