refactor: Expose public API from top-level module, sync API/docs

Author: pawamoy

src/mkdocstrings_handlers/c/__init__.py

@@ -6,13 +6,60 @@
     CInputOptions,
     COptions,
 )
-from mkdocstrings_handlers.c._internal.handler import CHandler, get_handler
+from mkdocstrings_handlers.c._internal.handler import (
+    CHandler,
+    CodeDoc,
+    Comment,
+    DocFunc,
+    DocGlobalVar,
+    DocMacro,
+    Docstring,
+    DocType,
+    FuncParam,
+    InOut,
+    Macro,
+    Param,
+    SupportsQualsAndType,
+    TypeDecl,
+    TypeRef,
+    ast_to_decl,
+    desc,
+    extract_comments,
+    extract_macros,
+    get_handler,
+    lookup_type_html,
+    parse_docstring,
+    tp_ref_to_str,
+    typedef_to_str,
+)
 
 __all__ = [
     "CConfig",
     "CHandler",
     "CInputConfig",
     "CInputOptions",
     "COptions",
+    "CodeDoc",
+    "Comment",
+    "DocFunc",
+    "DocGlobalVar",
+    "DocMacro",
+    "DocType",
+    "Docstring",
+    "FuncParam",
+    "InOut",
+    "Macro",
+    "Param",
+    "SupportsQualsAndType",
+    "TypeDecl",
+    "TypeRef",
+    "ast_to_decl",
+    "desc",
+    "extract_comments",
+    "extract_macros",
     "get_handler",
+    "lookup_type_html",
+    "parse_docstring",
+    "tp_ref_to_str",
+    "typedef_to_str",
 ]

src/mkdocstrings_handlers/c/_internal/handler.py

@@ -1,4 +1,4 @@
-"""This module implements a handler for the C language."""
+# This module implements a handler for the C language.
 
 from __future__ import annotations
 
@@ -10,33 +10,40 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Protocol
 
+from mkdocs.exceptions import PluginError
 from mkdocstrings import BaseHandler, CollectionError, CollectorItem, get_logger
 from pycparser import CParser, c_ast
 
+from mkdocstrings_handlers.c._internal.config import COptions
+
 if TYPE_CHECKING:
     from collections.abc import Mapping, MutableMapping
 
     from mkdocs.config.defaults import MkDocsConfig
     from pycparser.c_ast import FileAST
 
 
-logger = get_logger(__name__)
+_logger = get_logger(__name__)
 
 
 @dataclass
 class Comment:
     """A comment extracted from the source code."""
 
     text: str
+    """The text of the comment."""
     last_line_number: int
+    """The last line number of the comment in the source code."""
 
 
 @dataclass
 class Macro:
     """A macro extracted from the source code."""
 
     text: str
+    """The text of the macro."""
     line_number: int
+    """The line number of the macro in the source code."""
 
 
 _C_PARSER = CParser()
@@ -167,26 +174,35 @@ class InOut(str, Enum):
     """Enumeration for parameter direction."""
 
     UNSPECIFIED = "unspecified"
+    """The direction is unspecified."""
     IN = "in"
+    """The parameter is an input."""
     OUT = "out"
+    """The parameter is an output."""
 
 
 @dataclass
 class Param:
     """A parameter in a function signature."""
 
     name: str
+    """The name of the parameter."""
     desc: str
+    """The description of the parameter."""
     in_out: InOut
+    """The direction of the parameter (input, output, or unspecified)."""
 
 
 @dataclass
 class Docstring:
     """A parsed docstring."""
 
     desc: str
+    """The description of the docstring."""
     params: list[Param] | None = None
+    """The parameters of the docstring."""
     ret: str | None = None
+    """The return value of the docstring."""
 
 
 def parse_docstring(content: str) -> Docstring:
@@ -270,82 +286,113 @@ class DocMacro:
     """A parsed macro."""
 
     name: str
+    """The name of the macro."""
     content: str | None
+    """The content of the macro."""
     doc: Docstring | None
+    """The docstring of the macro."""
 
 
 @dataclass
 class DocType:
     """A parsed typedef."""
 
     name: str
+    """The name of the typedef."""
     tp: TypeRef
+    """The type reference of the typedef."""
     doc: Docstring | None
+    """The docstring of the typedef."""
     quals: list[str]
+    """The qualifiers of the typedef."""
 
 
 @dataclass
 class DocGlobalVar:
     """A parsed global variable."""
 
     name: str
+    """The name of the global variable."""
     tp: TypeRef
+    """The type reference of the global variable."""
     doc: Docstring | None
+    """The docstring of the global variable."""
     quals: list[str]
+    """The qualifiers of the global variable."""
 
 
 @dataclass
 class FuncParam:
     """A parameter in a function signature."""
 
     name: str
+    """The name of the parameter."""
     tp: TypeRef
+    """The type reference of the parameter."""
 
 
 @dataclass
 class DocFunc:
     """A parsed function."""
 
     name: str
+    """The name of the function."""
     args: list[FuncParam]
+    """The arguments of the function."""
     ret: TypeRef
+    """The return type of the function."""
     doc: Docstring | None
+    """The docstring of the function."""
 
 
 @dataclass
 class CodeDoc:
     """A parsed C source file."""
 
     macros: list[DocMacro]
+    """List of macros in the source file."""
     functions: list[DocFunc]
+    """"List of functions in the source file."""
     global_vars: list[DocGlobalVar]
+    """List of global variables in the source file."""
     typedefs: dict[str, DocType]
+    """List of typedefs in the source file."""
 
 
 class TypeDecl(str, Enum):
     """Enumeration for type declarations."""
 
     NORMAL = "normal"
+    """A normal type declaration."""
     POINTER = "pointer"
+    """A pointer type declaration."""
     ARRAY = "array"
+    """An array type declaration."""
     FUNCTION = "function"
+    """A function type declaration."""
 
 
 @dataclass
 class TypeRef:
     """A reference to a type in C."""
 
     name: TypeRef | str
+    """The name of the type reference."""
     decl: TypeDecl
+    """The type declaration of the type reference."""
     quals: list[str]
+    """The qualifiers of the type reference."""
     params: list[TypeRef] | None = None  # only in functions
+    """The parameters of the type reference."""
 
 
 class SupportsQualsAndType(Protocol):
     """A protocol for types that can have qualifiers and a type."""
 
     quals: list[str]
+    """The qualifiers of the type."""
     type: SupportsQualsAndType | c_ast.TypeDecl | c_ast.IdentifierType
+    """The type of the node."""
 
 
 def ast_to_decl(node: SupportsQualsAndType, types: dict[str, DocType]) -> TypeRef:
@@ -477,25 +524,6 @@ class CHandler(BaseHandler):
     fallback_theme: ClassVar[str] = "material"
     """The theme to fallback to."""
 
-    fallback_config: ClassVar[dict] = {"fallback": True}
-    """The configuration used to collect item during autorefs fallback."""
-
-    default_config: ClassVar[dict] = {
-        "show_root_heading": False,
-        "show_root_toc_entry": True,
-        "show_symbol_type_heading": True,
-        "show_symbol_type_toc_entry": True,
-        "heading_level": 2,
-    }
-    """The default configuration options.
-
-    Option | Type | Description | Default
-    ------ | ---- | ----------- | -------
-    **`show_root_heading`** | `bool` | Show the heading of the object at the root of the documentation tree. | `False`
-    **`show_root_toc_entry`** | `bool` | If the root heading is not shown, at least add a ToC entry for it. | `True`
-    **`heading_level`** | `int` | The initial heading level to use. | `2`
-    """
-
     def __init__(self, config: Mapping[str, Any], base_dir: Path, **kwargs: Any) -> None:
         """Initialize the handler.
 
@@ -507,14 +535,22 @@ def __init__(self, config: Mapping[str, Any], base_dir: Path, **kwargs: Any) ->
         super().__init__(**kwargs)
 
         self.config = config
+        """The handler configuration."""
         self.base_dir = base_dir
+        """The base directory of the project."""
         self.global_options = config.get("options", {})
+        """The global options for the handler."""
 
-    def get_options(self, local_options: Mapping[str, Any]) -> Mapping[str, Any]:
+    def get_options(self, local_options: Mapping[str, Any]) -> COptions:
         """Combine configuration options."""
-        return {**self.default_config, **self.global_options, **local_options}
-
-    def collect(self, identifier: str, options: MutableMapping[str, Any]) -> CollectorItem:
+        extra = {**self.global_options.get("extra", {}), **local_options.get("extra", {})}
+        options = {**self.global_options, **local_options, "extra": extra}
+        try:
+            return COptions.from_data(**options)
+        except Exception as error:
+            raise PluginError(f"Invalid options: {error}") from error
+
+    def collect(self, identifier: str, options: COptions) -> CollectorItem:
         """Collect data given an identifier and selection configuration.
 
         In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
@@ -530,7 +566,7 @@ def collect(self, identifier: str, options: MutableMapping[str, Any]) -> Collect
         Returns:
             Anything you want, as long as you can feed it to the `render` method.
         """
-        if options.get("fallback", False):
+        if options == {}:
             raise CollectionError("Not loading additional headers during fallback")
 
         source = Path(identifier).read_text(encoding="utf-8")
@@ -607,7 +643,7 @@ def collect(self, identifier: str, options: MutableMapping[str, Any]) -> Collect
 
         return CodeDoc(macros, funcs, global_vars, types)
 
-    def render(self, data: CodeDoc, options: MutableMapping[str, Any]) -> str:
+    def render(self, data: CodeDoc, options: COptions) -> str:
         """Render a template using provided data and configuration options.
 
         Parameters:
@@ -618,7 +654,7 @@ def render(self, data: CodeDoc, options: MutableMapping[str, Any]) -> str:
         Returns:
             The rendered template as HTML.
         """
-        heading_level = options["heading_level"]
+        heading_level = options.heading_level
         template = self.env.get_template("header.html.jinja")
         return template.render(
             config=options,