refactor: Move modules under internal folder, re-expose API from top-level

Author: pawamoy

src/griffe2md/__init__.py

@@ -6,5 +6,57 @@
 from __future__ import annotations
 
 from griffe2md._internal.cli import get_parser, main
+from griffe2md._internal.config import CONFIG_FILE_PATHS, ConfigDict, default_config, load_config
+from griffe2md._internal.main import (
+    prepare_context,
+    prepare_env,
+    render_object_docs,
+    render_package_docs,
+    write_package_docs,
+)
+from griffe2md._internal.rendering import (
+    Order,
+    do_any,
+    do_as_attributes_section,
+    do_as_classes_section,
+    do_as_functions_section,
+    do_as_modules_section,
+    do_filter_objects,
+    do_format_attribute,
+    do_format_code,
+    do_format_signature,
+    do_heading,
+    do_order_members,
+    do_split_path,
+    from_private_package,
+    order_map,
+)
 
-__all__: list[str] = ["get_parser", "main"]
+__all__: list[str] = [
+    "CONFIG_FILE_PATHS",
+    "ConfigDict",
+    "Order",
+    "default_config",
+    "do_any",
+    "do_as_attributes_section",
+    "do_as_classes_section",
+    "do_as_functions_section",
+    "do_as_modules_section",
+    "do_filter_objects",
+    "do_format_attribute",
+    "do_format_code",
+    "do_format_signature",
+    "do_heading",
+    "do_order_members",
+    "do_split_path",
+    "from_private_package",
+    "get_parser",
+    "load_config",
+    "main",
+    "order_map",
+    "prepare_context",
+    "prepare_env",
+    "render_object_docs",
+    "render_package_docs",
+    "write_package_docs",
+]

src/griffe2md/_internal/cli.py

@@ -1,5 +1,3 @@
-"""Module that contains the command line application."""
-
 # Why does this file exist, and why not put this in `__main__`?
 #
 # You might be tempted to import things from `__main__` later,
@@ -17,17 +15,17 @@
 import sys
 from typing import Any
 
-from griffe2md import debug
-from griffe2md.config import load_config
-from griffe2md.main import write_package_docs
+from griffe2md._internal import debug
+from griffe2md._internal.config import load_config
+from griffe2md._internal.main import write_package_docs
 
 
 class _DebugInfo(argparse.Action):
     def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
         super().__init__(nargs=nargs, **kwargs)
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
-        debug.print_debug_info()
+        debug._print_debug_info()
         sys.exit(0)
 
 
@@ -40,7 +38,7 @@ def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="griffe2md")
     parser.add_argument("package", help="The package to output Markdown docs for.")
     parser.add_argument("-o", "--output", default=None, help="File to write to. Default: stdout.")
-    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug.get_version()}")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
     parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
     return parser
 

src/griffe2md/config.py src/griffe2md/_internal/config.pysrc/griffe2md/config.py renamed to src/griffe2md/_internal/config.py

@@ -1,5 +1,3 @@
-"""Load configuration."""
-
 from __future__ import annotations
 
 import logging
@@ -16,13 +14,14 @@
 if TYPE_CHECKING:
     from re import Pattern
 
-logger = logging.getLogger(__name__)
+_logger = logging.getLogger(__name__)
 
 CONFIG_FILE_PATHS = (
     Path(".config/griffe2md.toml"),
     Path("config/griffe2md.toml"),
     Path("pyproject.toml"),
 )
+"""Paths to default configuration files."""
 
 
 def _locate_config_file() -> Path | None:
@@ -41,7 +40,7 @@ def load_config() -> ConfigDict | None:
     if not (config_path := _locate_config_file()):
         return None
 
-    logger.debug("Loading config from %s", config_path)
+    _logger.debug("Loading config from %s", config_path)
 
     with config_path.open("rb") as f:
         config = tomllib.load(f)
@@ -254,3 +253,4 @@ class ConfigDict(TypedDict):
     "show_docstring_functions": True,
     "show_docstring_modules": True,
 }
+"""Default configuration values."""

src/griffe2md/_internal/main.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, cast
+
+import mdformat
+from griffe import GriffeLoader, Parser
+from jinja2 import Environment, FileSystemLoader
+
+from griffe2md._internal import rendering
+from griffe2md._internal.config import ConfigDict, default_config
+
+if TYPE_CHECKING:
+    from griffe import Object
+
+
+def _output(text: str, to: IO | str | None = None) -> None:
+    if isinstance(to, str):
+        with open(to, "w") as output:
+            output.write(text)
+    else:
+        if to is None:
+            to = sys.stdout
+        to.write(text)
+
+
+def prepare_context(obj: Object, config: ConfigDict | None = None) -> dict:
+    """Prepare Jinja context.
+
+    Parameters:
+        obj: A Griffe object.
+        config: The configuration options.
+
+    Returns:
+        The Jinja context.
+    """
+    config = cast("ConfigDict", {**default_config, **(config or {})})
+    if config["filters"]:
+        config["filters"] = [
+            (re.compile(filtr.lstrip("!")), filtr.startswith("!")) if isinstance(filtr, str) else filtr
+            for filtr in config["filters"]
+        ]
+
+    heading_level = config["heading_level"]
+    try:
+        config["members_order"] = rendering.Order(config["members_order"]).value
+    except ValueError as error:
+        choices = "', '".join(item.value for item in rendering.Order)
+        raise ValueError(
+            f"Unknown members_order '{config['members_order']}', choose between '{choices}'.",
+        ) from error
+
+    summary = config["summary"]
+    if summary is True:
+        config["summary"] = {
+            "attributes": True,
+            "functions": True,
+            "classes": True,
+            "modules": True,
+        }
+    elif summary is False:
+        config["summary"] = {
+            "attributes": False,
+            "functions": False,
+            "classes": False,
+            "modules": False,
+        }
+    else:
+        config["summary"] = {
+            "attributes": summary.get("attributes", False),
+            "functions": summary.get("functions", False),
+            "classes": summary.get("classes", False),
+            "modules": summary.get("modules", False),
+        }
+
+    return {
+        "config": config,
+        obj.kind.value: obj,
+        "heading_level": heading_level,
+        "root": True,
+    }
+
+
+def prepare_env(env: Environment | None = None) -> Environment:
+    """Prepare Jinja environment.
+
+    Parameters:
+        env: A Jinja environment.
+
+    Returns:
+        The Jinja environment.
+    """
+    env = env or Environment(
+        autoescape=False,  # noqa: S701
+        loader=FileSystemLoader([Path(__file__).parent.parent / "templates"]),
+        auto_reload=False,
+    )
+    env.filters["any"] = rendering.do_any
+    env.filters["heading"] = rendering.do_heading
+    env.filters["as_attributes_section"] = rendering.do_as_attributes_section
+    env.filters["as_classes_section"] = rendering.do_as_classes_section
+    env.filters["as_functions_section"] = rendering.do_as_functions_section
+    env.filters["as_modules_section"] = rendering.do_as_modules_section
+    env.filters["filter_objects"] = rendering.do_filter_objects
+    env.filters["format_code"] = rendering.do_format_code
+    env.filters["format_signature"] = rendering.do_format_signature
+    env.filters["format_attribute"] = rendering.do_format_attribute
+    env.filters["order_members"] = rendering.do_order_members
+    env.filters["split_path"] = rendering.do_split_path
+    env.filters["stash_crossref"] = lambda ref, length: ref
+    env.filters["from_private_package"] = rendering.from_private_package
+
+    return env
+
+
+def render_object_docs(obj: Object, config: ConfigDict | None = None) -> str:
+    """Render docs for a given object.
+
+    Parameters:
+        obj: The Griffe object to render docs for.
+        config: The rendering configuration.
+
+    Returns:
+        Markdown.
+    """
+    env = prepare_env()
+    context = prepare_context(obj, config)
+    rendered = env.get_template(f"{obj.kind.value}.md.jinja").render(**context)
+    return mdformat.text(rendered)
+
+
+def render_package_docs(package: str, config: ConfigDict | None = None) -> str:
+    """Render docs for a given package.
+
+    Parameters:
+        package: The package (name) to render docs for.
+        config: The rendering configuration.
+
+    Returns:
+        Markdown.
+    """
+    config = cast("ConfigDict", {**default_config, **(config or {})})
+    parser = config["docstring_style"] and Parser(config["docstring_style"])
+    loader = GriffeLoader(docstring_parser=parser)
+    module = loader.load(package)
+    loader.resolve_aliases(external=True)
+    return render_object_docs(module, config)  # type: ignore[arg-type]
+
+
+def write_package_docs(
+    package: str,
+    config: ConfigDict | None = None,
+    output: IO | str | None = None,
+) -> None:
+    """Write docs for a given package to a file or stdout.
+
+    Parameters:
+        package: The package to render docs for.
+        config: The rendering configuration.
+        output: The file to write to.
+    """
+    _output(render_package_docs(package, config), to=output)