👌 IMPROVE: Allow namespace to be passed to to_docutils_ast (#46)

To allow for pre-compute caching

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
     )

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