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[source]#

A sentinel class for unset settings.

myst_parser.parsers.docutils_.DOCUTILS_UNSET = None#

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]][source]#

Convert an MdParserConfig attribute into a Docutils setting tuple.

Returns:

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

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

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_')[source]#

Create a configuration instance from the given settings.

class myst_parser.parsers.docutils_.Parser(rfc2822=False, inliner=None)[source]#

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()[source]#
parse(inputstring: str, document: docutils.nodes.document) None[source]#

Parse source text.

Parameters:
  • inputstring – The source string to parse

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

class myst_parser.parsers.docutils_.SimpleTranslator(document)[source]#

Bases: docutils.writers.html5_polyglot.HTMLTranslator

stylesheet_call(*args, **kwargs)[source]#
class myst_parser.parsers.docutils_.SimpleWriter[source]#

Bases: docutils.writers.html5_polyglot.Writer

settings_spec = None#
apply_template()[source]#
myst_parser.parsers.docutils_.cli_html(argv: Optional[List[str]] = None) None[source]#

Cmdline entrypoint for converting MyST to HTML.

myst_parser.parsers.docutils_.cli_html5(argv: Optional[List[str]] = None)[source]#

Cmdline entrypoint for converting MyST to HTML5.

myst_parser.parsers.docutils_.cli_html5_demo(argv: Optional[List[str]] = None)[source]#

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[source]#

Convert a MyST string to HTML5.

myst_parser.parsers.docutils_.cli_latex(argv: Optional[List[str]] = None)[source]#

Cmdline entrypoint for converting MyST to LaTeX.

myst_parser.parsers.docutils_.cli_xml(argv: Optional[List[str]] = None)[source]#

Cmdline entrypoint for converting MyST to XML.

myst_parser.parsers.docutils_.cli_pseudoxml(argv: Optional[List[str]] = None)[source]#

Cmdline entrypoint for converting MyST to pseudo-XML.

myst_parser.parsers.docutils_.visit_rubric_html(self, node)[source]#

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)[source]#

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)[source]#

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)[source]#

Override the default HTML depart method for container nodes.

See explanation in visit_container_html