diff --git a/rst_to_myst/namespace.py b/rst_to_myst/namespace.py index 2270610..2e0c5fd 100644 --- a/rst_to_myst/namespace.py +++ b/rst_to_myst/namespace.py @@ -182,7 +182,13 @@ def compile_namespace( default_domain="py", language_code="en", ) -> ApplicationNamespace: - """Gather all available directives and roles.""" + """Gather all available directives and roles. + + :param extensions: list of extensions to load + :param use_sphinx: whether to load sphinx extensions + :param default_domain: default domain to use + :param language_code: language code to use for translation + """ app = ApplicationNamespace( default_domain=default_domain, language_code=language_code ) diff --git a/rst_to_myst/parser.py b/rst_to_myst/parser.py index 63a2a54..7aa4c28 100644 --- a/rst_to_myst/parser.py +++ b/rst_to_myst/parser.py @@ -1,6 +1,6 @@ from functools import lru_cache from io import StringIO -from typing import Any, Dict, Tuple +from typing import Any, Dict, Iterable, Optional, Tuple import yaml from docutils import nodes @@ -21,7 +21,7 @@ from . import data as package_data from .inliner import InlinerMyst -from .namespace import compile_namespace +from .namespace import ApplicationNamespace, compile_namespace from .nodes import FrontMatterNode from .states import get_state_classes @@ -138,16 +138,32 @@ def _load_directive_data() -> Dict[str, Any]: def to_docutils_ast( text: str, uri: str = "source", - report_level=2, - halt_level=4, - warning_stream=None, - language_code="en", - use_sphinx=True, - extensions=(), - default_domain="py", - conversions=None, - front_matter=True, + report_level: int = 2, + halt_level: int = 4, + warning_stream: Optional[StringIO] = None, + language_code: str = "en", + use_sphinx: bool = True, + extensions: Iterable[str] = (), + default_domain: str = "py", + conversions: Optional[dict] = None, + front_matter: bool = True, + namespace: Optional[ApplicationNamespace] = None, ) -> Tuple[nodes.document, StringIO]: + """Convert a string of text to a docutils AST. + + :param text: The text to convert. + :param uri: The URI of the document. + :param report_level: The report level for docutils. + :param halt_level: The halt level for docutils. + :param warning_stream: A stream to write warnings to. + :param language_code: The language code for docutils. + :param use_sphinx: Whether to use Sphinx roles and directives. + :param extensions: A list of Sphinx extensions to use. + :param default_domain: The default Sphinx domain. + :param conversions: A dictionary of conversion functions. + :param front_matter: Whether to treat initial field list as front matter. + :param namespace: A pre-computed docutils namespace to use. + """ settings = OptionParser(components=(LosslessRSTParser,)).get_default_values() warning_stream = StringIO() if warning_stream is None else warning_stream settings.warning_stream = warning_stream @@ -160,11 +176,15 @@ def to_docutils_ast( document = new_document(uri, settings=settings) # compile lookup for directives/roles - namespace = compile_namespace( - language_code=language_code, - use_sphinx=use_sphinx, - extensions=extensions, - default_domain=default_domain, + namespace = ( + compile_namespace( + language_code=language_code, + use_sphinx=use_sphinx, + extensions=extensions, + default_domain=default_domain, + ) + if namespace is None + else namespace ) document.settings.namespace = namespace