myst_parser.parsers.docutils_ Namespace Reference

Classes
class	Parser
class	SimpleTranslator
class	SimpleWriter
class	Unset

Functions
int	_validate_int (setting, value, option_parser, config_parser=None, config_section=None)
set[str]	_validate_comma_separated_set (setting, value, option_parser, config_parser=None, config_section=None)
Callable[..., tuple[str,...]]	_create_validate_tuple (int length)
	_create_validate_yaml (Field field)
	_validate_url_schemes (setting, value, option_parser, config_parser=None, config_section=None)
tuple[dict[str, Any], str]	_attr_to_optparse_option (Field at, Any default)
tuple[str, list[str], dict[str, Any]]	attr_to_optparse_option (Field attribute, Any default, str prefix="myst_")
	create_myst_settings_spec (config_cls=MdParserConfig, str prefix="myst_")
	create_myst_config (frontend.Values settings, config_cls=MdParserConfig, str prefix="myst_")
	_run_cli (str writer_name, str writer_description, list[str]|None argv)
None	cli_html (list[str]|None argv=None)
	cli_html5 (list[str]|None argv=None)
	cli_html5_demo (list[str]|None argv=None)
str	to_html5_demo (str inputstring, **kwargs)
	cli_latex (list[str]|None argv=None)
	cli_xml (list[str]|None argv=None)
	cli_pseudoxml (list[str]|None argv=None)
	visit_rubric_html (self, node)
	depart_rubric_html (self, node)
	visit_container_html (self, nodes.Node node)
	depart_container_html (self, nodes.Node node)

Variables
	DOCUTILS_UNSET = Unset()

Detailed Description

MyST Markdown parser for docutils.

Function Documentation

_attr_to_optparse_option()

tuple[dict[str, Any], str] myst_parser.parsers.docutils_._attr_to_optparse_option ( Field  at, Any  default  )

protected

Convert a field into a Docutils optparse options dict.

:returns: (option_dict, default)

_create_validate_tuple()

Callable[..., tuple[str, ...]] myst_parser.parsers.docutils_._create_validate_tuple ( int  length )

protected

Create a validator for a tuple of length `length`.

_create_validate_yaml()

myst_parser.parsers.docutils_._create_validate_yaml ( Field  field )

protected

Create a deserializer/validator for a json setting.

_run_cli()

myst_parser.parsers.docutils_._run_cli ( str  writer_name, str  writer_description, list[str] | None  argv  )

protected

Run the command line interface for a particular writer.

_validate_comma_separated_set()

set[str] myst_parser.parsers.docutils_._validate_comma_separated_set (   setting,   value,   option_parser,   config_parser = None,   config_section = None  )

protected

Validate an integer setting.

_validate_int()

int myst_parser.parsers.docutils_._validate_int (   setting,   value,   option_parser,   config_parser = None,   config_section = None  )

protected

Validate an integer setting.

_validate_url_schemes()

myst_parser.parsers.docutils_._validate_url_schemes (   setting,   value,   option_parser,   config_parser = None,   config_section = None  )

protected

Validate a url_schemes setting.

This is a tricky one, because it can be either a comma-separated list or a YAML dictionary.

attr_to_optparse_option()

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

Convert an ``MdParserConfig`` attribute into a Docutils setting tuple.

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

cli_html()

None myst_parser.parsers.docutils_.cli_html

(

list[str] | None

argv = None

)

Cmdline entrypoint for converting MyST to HTML.

cli_html5()

myst_parser.parsers.docutils_.cli_html5

(

list[str] | None

argv = None

)

Cmdline entrypoint for converting MyST to HTML5.

cli_html5_demo()

myst_parser.parsers.docutils_.cli_html5_demo

(

list[str] | None

argv = 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.

cli_latex()

myst_parser.parsers.docutils_.cli_latex

(

list[str] | None

argv = None

)

Cmdline entrypoint for converting MyST to LaTeX.

cli_pseudoxml()

myst_parser.parsers.docutils_.cli_pseudoxml

(

list[str] | None

argv = None

)

Cmdline entrypoint for converting MyST to pseudo-XML.

cli_xml()

myst_parser.parsers.docutils_.cli_xml

(

list[str] | None

argv = None

)

Cmdline entrypoint for converting MyST to XML.

create_myst_config()

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

Create a configuration instance from the given settings.

create_myst_settings_spec()

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

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

depart_container_html()

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

Override the default HTML depart method for container nodes.

See explanation in `visit_container_html`

depart_rubric_html()

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

Override the default HTML visit method for rubric nodes.

See explanation in `visit_rubric_html`

to_html5_demo()

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

Convert a MyST string to HTML5.

visit_container_html()

myst_parser.parsers.docutils_.visit_container_html	(		self,
		nodes.Node	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

visit_rubric_html()

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