From eb7ba56ff2fe9b19dabdcbd91f6dc2a6fbcb1c39 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 28 Dec 2021 05:50:35 +0100 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20REFACTOR:=20`default=5Fpar?= =?UTF-8?q?ser`=20->=20`create=5Fmd=5Fparser`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `renderer` option has been removed from `MdParserConfig`, since it is not a configuration for the parser. Then the `default_parser` function has been replaced with `create_md_parser`, which directly takes the renderer class as a 2nd argument. --- docs/api/parsers.md | 9 ++++---- myst_parser/__init__.py | 5 ++--- myst_parser/cli.py | 6 ++++-- myst_parser/directives.py | 2 -- myst_parser/docutils_.py | 10 ++++----- myst_parser/main.py | 40 +++++++++++++++--------------------- myst_parser/sphinx_parser.py | 5 +++-- 7 files changed, 34 insertions(+), 43 deletions(-) diff --git a/docs/api/parsers.md b/docs/api/parsers.md index 7b499844..f9e66cc2 100644 --- a/docs/api/parsers.md +++ b/docs/api/parsers.md @@ -96,13 +96,14 @@ See the documentation of these tools for more information. ### Load a parser -To load one of these parsers for your own use, use the `default_parser` function. +To load one of these parsers for your own use, use the `create_md_parser` function. Below we'll create such a parser and show that it is an instance of a `markdown-it-py` parser: ```python -from myst_parser.main import default_parser, MdParserConfig -config = MdParserConfig(renderer="html") -parser = default_parser(config) +from markdown_it.renderer import RendererHTML +from myst_parser.main import create_md_parser, MdParserConfig +config = MdParserConfig() +parser = create_md_parser(config, RendererHTML) parser ``` diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py index 4dd24501..7be42c57 100644 --- a/myst_parser/__init__.py +++ b/myst_parser/__init__.py @@ -34,9 +34,8 @@ def setup_sphinx(app: "Sphinx"): app.add_post_transform(MystReferenceResolver) for name, default in MdParserConfig().as_dict().items(): - if not name == "renderer": - # TODO add types? - app.add_config_value(f"myst_{name}", default, "env") + # TODO add types? + app.add_config_value(f"myst_{name}", default, "env") app.connect("builder-inited", create_myst_config) app.connect("builder-inited", override_mathjax) diff --git a/myst_parser/cli.py b/myst_parser/cli.py index 4bea8cdf..267b373c 100644 --- a/myst_parser/cli.py +++ b/myst_parser/cli.py @@ -1,7 +1,9 @@ import argparse import sys -from myst_parser.main import MdParserConfig, default_parser +from markdown_it.renderer import RendererHTML + +from myst_parser.main import MdParserConfig, create_md_parser def print_anchors(args=None): @@ -25,7 +27,7 @@ def print_anchors(args=None): "-l", "--level", type=int, default=2, help="Maximum heading level." ) args = arg_parser.parse_args(args) - parser = default_parser(MdParserConfig(renderer="html", heading_anchors=args.level)) + parser = create_md_parser(MdParserConfig(heading_anchors=args.level), RendererHTML) def _filter_plugin(state): state.tokens = [ diff --git a/myst_parser/directives.py b/myst_parser/directives.py index 0d47dafd..5616cef8 100644 --- a/myst_parser/directives.py +++ b/myst_parser/directives.py @@ -61,8 +61,6 @@ def run(self) -> List[nodes.Node]: figclasses = self.options.pop("class", None) align = self.options.pop("align", None) - # parser = default_parser(self.env.myst_config) - node = nodes.Element() # TODO test that we are using myst parser # ensure html image enabled diff --git a/myst_parser/docutils_.py b/myst_parser/docutils_.py index 73bc5a7c..b937ec97 100644 --- a/myst_parser/docutils_.py +++ b/myst_parser/docutils_.py @@ -11,7 +11,8 @@ from docutils.parsers.rst import Parser as RstParser from markdown_it.token import Token -from myst_parser.main import MdParserConfig, default_parser +from myst_parser.docutils_renderer import DocutilsRenderer +from myst_parser.main import MdParserConfig, create_md_parser def _validate_int( @@ -63,8 +64,6 @@ def __repr__(self): "ref_domains", "update_mathjax", "mathjax_classes", - # We don't want to set the renderer from docutils.conf - "renderer", ) """Names of settings that cannot be set in docutils.conf.""" @@ -139,7 +138,6 @@ def create_myst_config(settings: frontend.Values): val = getattr(settings, setting, DOCUTILS_UNSET) if val is not DOCUTILS_UNSET: values[attribute.name] = val - values["renderer"] = "docutils" return MdParserConfig(**values) @@ -171,8 +169,8 @@ def parse(self, inputstring: str, document: nodes.document) -> None: config = create_myst_config(document.settings) except (TypeError, ValueError) as error: document.reporter.error(f"myst configuration invalid: {error.args[0]}") - config = MdParserConfig(renderer="docutils") - parser = default_parser(config) + config = MdParserConfig() + parser = create_md_parser(config, DocutilsRenderer) parser.options["document"] = document env: dict = {} tokens = parser.parse(inputstring, env) diff --git a/myst_parser/main.py b/myst_parser/main.py index 7663250e..615eb354 100644 --- a/myst_parser/main.py +++ b/myst_parser/main.py @@ -35,9 +35,6 @@ class MdParserConfig: Note in the sphinx configuration these option names are prepended with ``myst_`` """ - renderer: str = attr.ib( - default="sphinx", validator=in_(["sphinx", "html", "docutils"]) - ) commonmark_only: bool = attr.ib( default=False, validator=instance_of(bool), @@ -196,32 +193,27 @@ def as_dict(self, dict_factory=dict) -> dict: return attr.asdict(self, dict_factory=dict_factory) -def default_parser(config: MdParserConfig) -> MarkdownIt: - """Return the default parser configuration for MyST""" - renderer_cls: Callable[[MarkdownIt], RendererProtocol] - - if config.renderer == "sphinx": - from myst_parser.sphinx_renderer import SphinxRenderer +def default_parser(config: MdParserConfig): + raise NotImplementedError( + "default_parser has been deprecated and replaced by create_md_parser." + "You must also supply the renderer class directly to create_md_parser." + ) - renderer_cls = SphinxRenderer - elif config.renderer == "html": - renderer_cls = RendererHTML - elif config.renderer == "docutils": - from myst_parser.docutils_renderer import DocutilsRenderer - renderer_cls = DocutilsRenderer - else: - raise ValueError("unknown renderer type: {0}".format(config.renderer)) +def create_md_parser( + config: MdParserConfig, renderer: Callable[[MarkdownIt], RendererProtocol] +) -> MarkdownIt: + """Return a Markdown parser with the required MyST configuration.""" if config.commonmark_only: - md = MarkdownIt("commonmark", renderer_cls=renderer_cls).use( + md = MarkdownIt("commonmark", renderer_cls=renderer).use( wordcount_plugin, per_minute=config.words_per_minute ) md.options.update({"commonmark_only": True}) return md md = ( - MarkdownIt("commonmark", renderer_cls=renderer_cls) + MarkdownIt("commonmark", renderer_cls=renderer) .enable("table") .use(front_matter_plugin) .use(myst_block_plugin) @@ -299,6 +291,7 @@ def default_parser(config: MdParserConfig) -> MarkdownIt: def to_docutils( text: str, parser_config: Optional[MdParserConfig] = None, + *, options=None, env=None, document=None, @@ -320,8 +313,9 @@ def to_docutils( :returns: docutils document """ from myst_parser.docutils_renderer import make_document + from myst_parser.sphinx_renderer import SphinxRenderer - md = default_parser(parser_config or MdParserConfig()) + md = create_md_parser(parser_config or MdParserConfig(), SphinxRenderer) if options: md.options.update(options) md.options["document"] = document or make_document() @@ -340,13 +334,11 @@ def to_html(text: str, env=None, config: Optional[MdParserConfig] = None): This is mainly for test purposes only. """ config = config or MdParserConfig() - config.renderer = "html" - md = default_parser(config) + md = create_md_parser(config, RendererHTML) return md.render(text, env) def to_tokens(text: str, env=None, config: Optional[MdParserConfig] = None): config = config or MdParserConfig() - config.renderer = "html" - md = default_parser(config) + md = create_md_parser(config, RendererHTML) return md.parse(text, env) diff --git a/myst_parser/sphinx_parser.py b/myst_parser/sphinx_parser.py index 86ee64fb..7799d498 100644 --- a/myst_parser/sphinx_parser.py +++ b/myst_parser/sphinx_parser.py @@ -12,7 +12,8 @@ from sphinx.util import logging from sphinx.util.docutils import sphinx_domains -from myst_parser.main import default_parser +from myst_parser.main import create_md_parser +from myst_parser.sphinx_renderer import SphinxRenderer SPHINX_LOGGER = logging.getLogger(__name__) @@ -49,7 +50,7 @@ def parse(self, inputstring: str, document: nodes.document) -> None: """ config = document.settings.env.myst_config - parser = default_parser(config) + parser = create_md_parser(config, SphinxRenderer) parser.options["document"] = document env: dict = {} tokens = parser.parse(inputstring, env)