docs: Update documentation templates and macros (#55)

* docs: Update documentation templates and macros * ci: remove broken pre-commit hook
tektronix · Oct 22, 2024 · 0b5622e · 0b5622e
1 parent 1bdf67e
commit 0b5622e
Show file tree

Hide file tree

Showing 5 changed files with 74 additions and 35 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -143,8 +143,9 @@ repos:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
-  - repo: https://github.com/PyCQA/docformatter
-    rev: dfefe062799848234b4cd60b04aa633c0608025e  # frozen: v1.7.5
-    hooks:
-      - id: docformatter
-        additional_dependencies: [tomli]
+  # TODO: Re-enable this once https://github.com/PyCQA/docformatter/issues/293 is resolved
+  #  - repo: https://github.com/PyCQA/docformatter
+  #    rev: dfefe062799848234b4cd60b04aa633c0608025e  # frozen: v1.7.5
+  #    hooks:
+  #      - id: docformatter
+  #        additional_dependencies: [tomli]
diff --git a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja
@@ -5,7 +5,7 @@ This template iterates on members of a given object and renders them.
 It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
 
 Context:
-  obj (griffe.dataclasses.Object): The object to render.
+  obj (griffe.Object): The object to render.
   config (dict): The configuration options.
   root_members (bool): Whether the object is the root object.
   heading_level (int): The HTML heading level to use.
@@ -31,7 +31,7 @@ Context:
     </table>
 {%- endmacro -%}
 
-{% if obj.members %}
+{% if obj.all_members %}
   {% block logs scoped %}
     {#- Logging block.
 
@@ -97,7 +97,7 @@ Context:
             filters=config.filters,
             members_list=members_list,
             inherited_members=config.inherited_members,
-            keep_no_docstrings=config.show_if_no_docstring)|selectattr("is_init_module", "equalto", false)|list|order_members(config.members_order, members_list)
+            keep_no_docstrings=config.show_if_no_docstring)|selectattr("is_init_module", "equalto", false)|list|order_members(config.members_order, members_list)|sort(attribute="name")
         %}
             {% if modules %}
                 {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
@@ -127,7 +127,7 @@ Context:
                 {% endif %}
                 {% with heading_level = heading_level + extra_level %}
                   {% for attribute in attributes|order_members(config.members_order, members_list) %}
-                    {% if members_list is not none or attribute.is_public %}
+                    {% if members_list is not none or (not attribute.is_imported or attribute.is_public) %}
                       {% include attribute|get_template with context %}
                     {% endif %}
                   {% endfor %}
@@ -147,7 +147,7 @@ Context:
                 {% endif %}
                 {% with heading_level = heading_level + extra_level %}
                   {% for class in classes|order_members(config.members_order, members_list) %}
-                    {% if members_list is not none or class.is_public %}
+                    {% if members_list is not none or (not class.is_imported or class.is_public) %}
                       {% include class|get_template with context %}
                     {% endif %}
                   {% endfor %}
@@ -168,7 +168,7 @@ Context:
                 {% with heading_level = heading_level + extra_level %}
                   {% for function in functions|order_members(config.members_order, members_list) %}
                     {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
-                      {% if members_list is not none or function.is_public %}
+                      {% if members_list is not none or (not function.is_imported or function.is_public) %}
                         {% include function|get_template with context %}
                       {% endif %}
                     {% endif %}
@@ -189,8 +189,8 @@ Context:
                     {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
                   {% endif %}
                   {% with heading_level = heading_level + extra_level %}
-                    {% for module in modules|order_members(config.members_order, members_list) %}
-                      {% if members_list is not none or module.is_public %}
+                    {% for module in modules|order_members(config.members_order.alphabetical, members_list) %}
+                      {% if members_list is not none or (not module.is_alias or module.is_public) %}
                         {% include module|get_template with context %}
                       {% endif %}
                     {% endfor %}

diff --git a/docs/generate_api_pages.py b/docs/generate_api_pages.py
@@ -43,7 +43,7 @@ def sort_paths(path_object: Path) -> Tuple[int, str]:
         parts = parts[:-1]
         doc_path = doc_path.with_name("index.md")
         full_doc_path = full_doc_path.with_name("index.md")
-    elif parts[-1] == "__main__":
+    elif parts[-1] == "__main__" or parts[-1].startswith("_"):
         continue
 
     nav[parts] = doc_path.as_posix()

diff --git a/docs/macros.py b/docs/macros.py
@@ -1,5 +1,6 @@
 """Macros for the documentation."""
 
+import abc
 import inspect
 import os
 import pathlib
@@ -10,24 +11,22 @@
 
 import tomli
 
-from mkdocs_macros.plugin import MacrosPlugin  # pyright: ignore[reportMissingTypeStubs]
+from mkdocs_macros.plugin import MacrosPlugin
 
 HEADER_ONE_REGEX = re.compile(r"^#\s(.+)$", re.MULTILINE)
 PAGE_REPLACEMENTS = {}
 FILES_TO_REMOVE_BLACK_FORMATTER_DISABLE_COMMENT = {
     "basic_usage.md",
 }
-
-
-####################################################################################################
-# Helper functions
-####################################################################################################
 CONVERSION_PATTERN = re.compile(
     r"> \[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION|DANGER)]\s*>\s*(.*?)(?=\n[^>]|$)",
     re.IGNORECASE | re.DOTALL,
 )
 
 
+####################################################################################################
+# Helper functions
+####################################################################################################
 def convert_gfm_alerts_to_admonitions(content: str) -> str:
     """Convert GitHub Flavored Markdown (GFM) alerts to MkDocs admonitions.
 
@@ -119,11 +118,15 @@ def get_classes(*cls_or_modules: str, strict: bool = False) -> Generator[Any, No
 ####################################################################################################
 # Macro functions
 ####################################################################################################
-def class_diagram(
+def class_diagram(  # noqa: C901  # pylint: disable=too-many-locals
     *cls_or_modules: str,
     full: bool = False,
     strict: bool = False,
     namespace: Optional[str] = None,
+    tree_direction: str = "up",
+    chart_direction: str = "LR",
+    highlight_family_base_classes: bool = False,
+    highlight_device_drivers: bool = False,
 ) -> str:
     """Create a mermaid classDiagram for the provided classes or modules.
 
@@ -133,6 +136,13 @@ def class_diagram(
         strict: A boolean indicating to only consider classes that are strictly defined in that
             module and not imported from somewhere else.
         namespace: Limits the diagram to only include classes defined in this namespace.
+        tree_direction: A string indicating the direction of traversal in the class hierarchy,
+            either "up" or "down".
+        chart_direction: A string indicating the direction of the chart, either
+            "LR" (left to right), "RL" (right to left),
+            "TB" (top to bottom), or "BT" (bottom to top).
+        highlight_family_base_classes: Indicate to highlight the family base classes in cyan.
+        highlight_device_drivers: Indicate to highlight the device drivers in lightgreen.
 
     Returns:
         The mermaid code block with complete syntax for the classDiagram.
@@ -141,16 +151,38 @@ def class_diagram(
         ValueError: If no classDiagram can be created.
     """
     inheritances: Set[Tuple[str, str]] = set()
+    family_base_classes: Set[str] = set()
+    device_drivers: Set[str] = set()
+
+    def get_tree_upwards(cls: Any) -> None:
+        if getattr(cls, "_product_family_base_class", None) == cls:
+            family_base_classes.add(cls.__name__)
+        if abc.ABC not in cls.__bases__:
+            device_drivers.add(cls.__name__)
 
-    def get_tree(cls: Any) -> None:
         for base in cls.__bases__:
             if base.__name__ == "object":
                 continue
             if namespace and not base.__module__.startswith(namespace):
                 continue
             inheritances.add((base.__name__, cls.__name__))
             if full:
-                get_tree(base)
+                get_tree_upwards(base)
+
+    def get_tree_downwards(cls: Any) -> None:
+        if getattr(cls, "_product_family_base_class", None) == cls:
+            family_base_classes.add(cls.__name__)
+        if abc.ABC not in cls.__bases__:
+            device_drivers.add(cls.__name__)
+
+        for subclass in cls.__subclasses__():
+            if namespace and not subclass.__module__.startswith(namespace):
+                continue
+            inheritances.add((cls.__name__, subclass.__name__))
+            if full:
+                get_tree_downwards(subclass)
+
+    get_tree = get_tree_upwards if tree_direction == "up" else get_tree_downwards
 
     for cls_item in get_classes(*cls_or_modules, strict=strict):
         get_tree(cls_item)
@@ -159,11 +191,18 @@ def get_tree(cls: Any) -> None:
         msg = "No class hierarchy can be created."
         raise ValueError(msg)
 
-    return (
-        "```mermaid\nclassDiagram\n"
-        + "\n".join(f"  {a} <|-- {b}" for a, b in sorted(inheritances))
-        + "\n```"
+    mermaid_code_block = f"```mermaid\nclassDiagram\n  direction {chart_direction}\n" + "\n".join(
+        f"  {a} <|-- {b}" for a, b in sorted(inheritances)
     )
+    if highlight_family_base_classes:
+        for family_base_class in sorted(family_base_classes):
+            mermaid_code_block += f"\n  style {family_base_class} stroke:orangered,stroke-width:4px"
+    if highlight_device_drivers:
+        for device_driver in sorted(device_drivers):
+            mermaid_code_block += f"\n  style {device_driver} fill:lightgreen"
+    mermaid_code_block += "\n```"
+
+    return mermaid_code_block
 
 
 def create_repo_link(link_text: str, base_repo_url: str, relative_repo_path: str) -> str:
@@ -191,8 +230,7 @@ def define_env(env: MacrosPlugin) -> None:
     """
     # Read in the current package version number to use in templates and files
     with open(
-        pathlib.Path(f"{pathlib.Path(__file__).parents[1]}") / "pyproject.toml",
-        "rb",
+        pathlib.Path(f"{pathlib.Path(__file__).parents[1]}") / "pyproject.toml", "rb"
     ) as file_handle:
         pyproject_data = tomli.load(file_handle)
         package_version = "v" + pyproject_data["tool"]["poetry"]["version"]
@@ -212,16 +250,16 @@ def define_env(env: MacrosPlugin) -> None:
 def on_post_page_macros(env: MacrosPlugin) -> None:
     """Post-process pages."""
     # Check if there are any replacements to perform on the page
-    if env.page.file.src_path in PAGE_REPLACEMENTS:  # pyright: ignore[reportUnknownMemberType]
-        for search, replace in PAGE_REPLACEMENTS[env.page.file.src_path]:  # pyright: ignore[reportUnknownMemberType]
-            env.markdown = env.markdown.replace(search, replace)  # pyright: ignore[reportUnknownMemberType]
+    if env.page.file.src_path in PAGE_REPLACEMENTS:
+        for search, replace in PAGE_REPLACEMENTS[env.page.file.src_path]:
+            env.markdown = env.markdown.replace(search, replace)
     # Check if all black format disable comments should be removed from the page
     if env.page.file.src_path in FILES_TO_REMOVE_BLACK_FORMATTER_DISABLE_COMMENT:  # pyright: ignore[reportUnknownMemberType]
         env.markdown = env.markdown.replace("# fmt: off\n", "")  # pyright: ignore[reportUnknownMemberType]
     # Check if there are any admonitions to replace on the page
     env.markdown = convert_gfm_alerts_to_admonitions(env.markdown)  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
     # Check if the title is correct
-    if actual_title_match := HEADER_ONE_REGEX.search(env.markdown):  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
+    if actual_title_match := HEADER_ONE_REGEX.search(env.markdown):
         actual_title = actual_title_match.group(1)
         if env.page.title != actual_title:  # pyright: ignore[reportUnknownMemberType]
-            env.page.title = actual_title  # pyright: ignore[reportUnknownMemberType]
+            env.page.title = actual_title  # pyright: ignore[reportAttributeAccessIssue]
diff --git a/pyproject.toml b/pyproject.toml
@@ -60,7 +60,7 @@ numpy = [
   {python = "^3.8, <3.12", version = "^1.24"}
 ]
 pydantic = "^2.7.4"
-python = "^3.8"
+python = "^3.8, <3.13"
 python-dateutil = "^2.8.2"
 scipy = [
   {python = "^3.9", version = "^1.12"},