refactor: Sync API and docs

Author: pawamoy

duties.py

@@ -93,7 +93,7 @@ def check_quality(ctx: Context) -> None:
     )
 
 
-@duty(skip_if=sys.version_info[:2] != (3, 12), skip_reason="Docs build only on Python 3.12")
+@duty(skip_if=sys.version_info[:2] != (3, 12), skip_reason=pyprefix("Docs build only on Python 3.12"))
 def check_docs(ctx: Context) -> None:
     """Check if the documentation builds correctly."""
     Path("htmlcov").mkdir(parents=True, exist_ok=True)

mkdocs.yml

@@ -141,7 +141,6 @@ plugins:
           docstring_options:
             ignore_init_summary: true
           docstring_section_style: list
-          filters: ["!^_"]
           heading_level: 1
           inherited_members: true
           merge_init_into_class: true

src/markdown_exec/_internal/formatters/base.py

@@ -18,8 +18,10 @@
 
     from markdown.core import Markdown
 
-logger = get_logger(__name__)
+_logger = get_logger(__name__)
+
 default_tabs = ("Source", "Result")
+"""Default tab titles."""
 
 
 @contextmanager
@@ -74,6 +76,7 @@ class ExecutionError(Exception):
     def __init__(self, message: str, returncode: int | None = None) -> None:
         super().__init__(message)
         self.returncode = returncode
+        """The code returned by the execution of the code block."""
 
 
 def _format_log_details(details: str, *, strip_fences: bool = False) -> str:
@@ -151,7 +154,7 @@ def base_format(
             f"Code block is:\n\n{_format_log_details(source_input)}\n\n"
             f"Output is:\n\n{_format_log_details(str(error), strip_fences=True)}\n"
         )
-        logger.warning(log_message)
+        _logger.warning(log_message)
         return markdown.convert(str(error))
 
     if not output and not source:

src/markdown_exec/_internal/formatters/console.py

@@ -12,7 +12,7 @@
 if TYPE_CHECKING:
     from markupsafe import Markup
 
-logger = get_logger(__name__)
+_logger = get_logger(__name__)
 
 
 def _transform_source(code: str) -> tuple[str, str]:

src/markdown_exec/_internal/formatters/pycon.py

@@ -6,13 +6,10 @@
 
 from markdown_exec._internal.formatters.base import base_format
 from markdown_exec._internal.formatters.python import _run_python
-from markdown_exec._internal.logger import get_logger
 
 if TYPE_CHECKING:
     from markupsafe import Markup
 
-logger = get_logger(__name__)
-
 
 def _transform_source(code: str) -> tuple[str, str]:
     python_lines = []

src/markdown_exec/_internal/formatters/pyodide.py

@@ -10,18 +10,20 @@
 # All Ace.js themes listed here:
 # https://github.com/ajaxorg/ace/tree/master/src/theme
 
-play_emoji = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8 5.14v14l11-7-11-7Z"></path></svg>'
-clear_emoji = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.14 3c-.51 0-1.02.2-1.41.59L2.59 14.73c-.78.77-.78 2.04 0 2.83L5.03 20h7.66l8.72-8.73c.79-.77.79-2.04 0-2.83l-4.85-4.85c-.39-.39-.91-.59-1.42-.59M17 18l-2 2h7v-2"></path></svg>'
+_play_emoji = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8 5.14v14l11-7-11-7Z"></path></svg>'
+)
+_clear_emoji = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.14 3c-.51 0-1.02.2-1.41.59L2.59 14.73c-.78.77-.78 2.04 0 2.83L5.03 20h7.66l8.72-8.73c.79-.77.79-2.04 0-2.83l-4.85-4.85c-.39-.39-.91-.59-1.42-.59M17 18l-2 2h7v-2"></path></svg>'
 
-assets = """
+_assets = """
 <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.16.0/ace.js"></script>
 <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
 <script type="text/javascript" src="https://cdn.jsdelivr.net/pyodide/v{version}/full/pyodide.js"></script>
 <link title="light" rel="alternate stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/tomorrow.min.css" disabled="disabled">
 <link title="dark" rel="alternate stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/tomorrow-night-blue.min.css" disabled="disabled">
 """
 
-template = """
+_template = """
 <div class="pyodide">
 <div class="pyodide-editor-bar">
 <span class="pyodide-bar-item">Editor (session: %(session)s)</span><span id="%(id_prefix)srun" title="Run: press Ctrl-Enter" class="pyodide-bar-item pyodide-clickable"><span class="twemoji">%(play_emoji)s</span> Run</span>
@@ -62,10 +64,10 @@ def _format_pyodide(code: str, md: Markdown, session: str, extra: dict, **option
         "theme_light": theme_light.strip(),
         "theme_dark": theme_dark.strip(),
         "session": session or "default",
-        "play_emoji": play_emoji,
-        "clear_emoji": clear_emoji,
+        "play_emoji": _play_emoji,
+        "clear_emoji": _clear_emoji,
     }
-    rendered = template % data
+    rendered = _template % data
     if exclude_assets:
         return rendered
-    return assets.format(version=version) + rendered
+    return _assets.format(version=version) + rendered

src/markdown_exec/_internal/mkdocs_plugin.py

@@ -13,8 +13,8 @@
 from mkdocs.plugins import BasePlugin
 from mkdocs.utils import write_file
 
-from markdown_exec import formatter, formatters, validator
 from markdown_exec._internal.logger import patch_loggers
+from markdown_exec._internal.main import formatter, formatters, validator
 from markdown_exec._internal.rendering import MarkdownConverter, markdown_config
 
 if TYPE_CHECKING:
@@ -27,9 +27,9 @@
 try:
     __import__("pygments_ansi_color")
 except ImportError:
-    ansi_ok = False
+    _ansi_ok = False
 else:
-    ansi_ok = True
+    _ansi_ok = True
 
 
 class _LoggerAdapter(logging.LoggerAdapter):
@@ -71,7 +71,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         In this hook, we add custom fences for all the supported languages.
 
         We also save the Markdown extensions configuration
-        into [`markdown_config`][markdown_exec.rendering.markdown_config].
+        into [`markdown_config`][markdown_exec.markdown_config].
 
         Arguments:
             config: The MkDocs config object.
@@ -82,7 +82,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         if "pymdownx.superfences" not in config["markdown_extensions"]:
             message = "The 'markdown-exec' plugin requires the 'pymdownx.superfences' Markdown extension to work."
             raise PluginError(message)
-        if self.config.ansi in ("required", True) and not ansi_ok:
+        if self.config.ansi in ("required", True) and not _ansi_ok:
             raise PluginError(
                 "The configuration for the 'markdown-exec' plugin requires "
                 "that it is installed with the 'ansi' extra. "
@@ -113,14 +113,16 @@ def on_env(
         config: MkDocsConfig,
         files: Files,  # noqa: ARG002
     ) -> Environment | None:
-        if self.config.ansi in ("required", True) or (self.config.ansi == "auto" and ansi_ok):
+        """Add assets to the environment."""
+        if self.config.ansi in ("required", True) or (self.config.ansi == "auto" and _ansi_ok):
             self._add_css(config, "ansi.css")
         if "pyodide" in self.languages:
             self._add_css(config, "pyodide.css")
             self._add_js(config, "pyodide.js")
         return env
 
     def on_post_build(self, *, config: MkDocsConfig) -> None:  # noqa: ARG002
+        """Reset the plugin state."""
         MarkdownConverter.counter = 0
         markdown_config.reset()
         if self.mkdocs_config_dir is None:
@@ -130,7 +132,7 @@ def on_post_build(self, *, config: MkDocsConfig) -> None:  # noqa: ARG002
 
     def _add_asset(self, config: MkDocsConfig, asset_file: str, asset_type: str) -> None:
         asset_filename = f"assets/_markdown_exec_{asset_file}"
-        asset_content = Path(__file__).parent.joinpath("assets", asset_file).read_text()
+        asset_content = Path(__file__).parent.parent.joinpath("assets", asset_file).read_text()
         write_file(asset_content.encode("utf-8"), os.path.join(config.site_dir, asset_filename))
         config[f"extra_{asset_type}"].insert(0, asset_filename)
 

src/markdown_exec/_internal/processors.py

@@ -21,12 +21,15 @@ class IdPrependingTreeprocessor(Treeprocessor):
     """Prepend the configured prefix to IDs of all HTML elements."""
 
     name = "markdown_exec_ids"
+    """The name of the treeprocessor."""
 
     def __init__(self, md: Markdown, id_prefix: str) -> None:
         super().__init__(md)
         self.id_prefix = id_prefix
+        """The prefix to prepend to IDs."""
 
     def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
         if not self.id_prefix:
             return
         for el in root.iter():
@@ -53,13 +56,17 @@ class HeadingReportingTreeprocessor(Treeprocessor):
     """Records the heading elements encountered in the document."""
 
     name = "markdown_exec_record_headings"
+    """The name of the treeprocessor."""
     regex = re.compile("[Hh][1-6]")
+    """The regex to match heading tags."""
 
     def __init__(self, md: Markdown, headings: list[Element]):
         super().__init__(md)
         self.headings = headings
+        """The list of heading elements."""
 
     def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
         for el in root.iter():
             if self.regex.fullmatch(el.tag):
                 el = copy.copy(el)  # noqa: PLW2901
@@ -74,6 +81,7 @@ class InsertHeadings(Treeprocessor):
     """Our headings insertor."""
 
     name = "markdown_exec_insert_headings"
+    """The name of the treeprocessor."""
 
     def __init__(self, md: Markdown):
         """Initialize the object.
@@ -83,8 +91,10 @@ def __init__(self, md: Markdown):
         """
         super().__init__(md)
         self.headings: dict[Markup, list[Element]] = {}
+        """The dictionary of headings."""
 
     def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
         if not self.headings:
             return
 
@@ -103,8 +113,10 @@ class RemoveHeadings(Treeprocessor):
     """Our headings remover."""
 
     name = "markdown_exec_remove_headings"
+    """The name of the treeprocessor."""
 
     def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
         self._remove_duplicated_headings(root)
 
     def _remove_duplicated_headings(self, parent: Element) -> None:

src/markdown_exec/_internal/rendering.py

@@ -113,19 +113,22 @@ class MarkdownConfig:
     """This class returns a singleton used to store Markdown extensions configuration.
 
     You don't have to instantiate the singleton yourself:
-    we provide it as [`markdown_config`][markdown_exec.rendering.markdown_config].
+    we provide it as [`markdown_config`][markdown_exec.markdown_config].
     """
 
     _singleton: MarkdownConfig | None = None
 
     def __new__(cls) -> MarkdownConfig:  # noqa: PYI034
+        """Return the singleton instance."""
         if cls._singleton is None:
             cls._singleton = super().__new__(cls)
         return cls._singleton
 
     def __init__(self) -> None:
         self.exts: list[str] | None = None
+        """The Markdown extensions."""
         self.exts_config: dict[str, dict[str, Any]] | None = None
+        """The extensions configuration."""
 
     def save(self, exts: list[str], exts_config: dict[str, dict[str, Any]]) -> None:
         """Save Markdown extensions and their configuration.
@@ -156,9 +159,9 @@ def reset(self) -> None:
 markdown_config.save(extensions, extensions_config)
 ```
 
-See the actual event hook: [`on_config`][markdown_exec.mkdocs_plugin.MarkdownExecPlugin.on_config].
-See the [`save`][markdown_exec.rendering.MarkdownConfig.save]
-and [`reset`][markdown_exec.rendering.MarkdownConfig.reset] methods.
+See the actual event hook: [`on_config`][markdown_exec.MarkdownExecPlugin.on_config].
+See the [`save`][markdown_exec.MarkdownConfig.save]
+and [`reset`][markdown_exec.MarkdownConfig.reset] methods.
 
 Without it, Markdown Exec will rely on the `registeredExtensions` attribute
 of the original Markdown instance, which does not forward everything
@@ -233,6 +236,7 @@ class MarkdownConverter:
     """Helper class to avoid breaking the original Markdown instance state."""
 
     counter: int = 0
+    """A counter to generate unique IDs for code blocks."""
 
     def __init__(self, md: Markdown, *, update_toc: bool = True) -> None:
         self._md_ref: Markdown = md

src/markdown_exec/formatters/__init__.py

@@ -0,0 +1,17 @@
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal import formatters
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(formatters, name)

src/markdown_exec/formatters/base.py

@@ -0,0 +1,17 @@
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal.formatters import base
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.base` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(base, name)

src/markdown_exec/formatters/bash.py

@@ -0,0 +1,17 @@
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal.formatters import bash
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.bash` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(bash, name)

src/markdown_exec/formatters/console.py

@@ -0,0 +1,17 @@
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal.formatters import console
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.console` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(console, name)

src/markdown_exec/formatters/markdown.py

@@ -0,0 +1,17 @@
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal.formatters import markdown
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.markdown` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(markdown, name)

src/markdown_exec/formatters/pycon.py

@@ -0,0 +1,17 @@
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal.formatters import pycon
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.pycon` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(pycon, name)