Improve documentation look & feel via MkDocs Material template enhancements (#5)
# Improve documentation look & feel via MkDocs Material template enhancements ## Summary This MR improves the overall **documentation experience and visual presentation** of the doc-forge docs by enhancing the MkDocs Material template configuration. The changes focus on **navigation usability, code readability, and richer Markdown rendering**, resulting in a cleaner and more professional documentation site. Docstring changes were made across the codebase for consistency, but this MR description focuses on the **template and presentation improvements**. --- ## Navigation Improvements The navigation system has been enhanced to provide a clearer structure and better discoverability. Key improvements include: * Section-aware navigation in the sidebar * Automatic expansion of module/package hierarchy * Scroll tracking within the sidebar * Clickable package index pages Material navigation features added: * `navigation.sections` * `navigation.expand` * `navigation.tracking` * `navigation.indexes` This results in a **single cohesive navigation tree** that exposes the entire documentation hierarchy from the sidebar. --- ## Code Block Improvements Code blocks previously appeared relatively plain. The template now enables richer syntax highlighting and improved readability. Enhancements include: * Syntax highlighting using `pymdownx.highlight` * Line numbers for code blocks * Anchored line numbers for deep linking * Improved fenced code block rendering Additional Material features: * `content.code.copy` — copy button for code blocks * `content.code.annotate` — support for code annotations These changes significantly improve the readability of examples and API snippets throughout the documentation. --- ## Markdown Rendering Enhancements Additional Markdown extensions were enabled to support richer documentation features: * `pymdownx.superfences` for advanced fenced blocks * `pymdownx.inlinehilite` for inline code highlighting * `pymdownx.snippets` for reusable snippets * `admonition` and `pymdownx.details` for callouts and collapsible sections * `pymdownx.tabbed` for tabbed content blocks * `pymdownx.tasklist` for checklist-style items * `tables`, `footnotes`, and advanced formatting extensions These extensions make it easier to write expressive and structured documentation. --- ## Search Experience The documentation search experience has been improved using Material search features: * `search.highlight` * `search.share` * `search.suggest` These enhancements provide: * highlighted search matches * sharable search URLs * auto-suggestions while typing --- ## mkdocstrings Improvements The mkdocstrings configuration has been expanded to produce clearer API documentation. Notable improvements include: * grouping objects by category * explicit category headings * improved symbol headings * cleaner object path display This results in more structured API documentation pages. --- ## Result Overall, these changes provide: * cleaner and more intuitive navigation * significantly improved code presentation * richer Markdown capabilities * better search usability The documentation now has a **more polished, modern appearance** and improved usability for both readers and contributors. Reviewed-on: #5 Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com> Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
This commit is contained in:
@@ -1,6 +1,9 @@
|
||||
"""
|
||||
This module provides the GriffeLoader, which uses the 'griffe' library to
|
||||
introspect Python source code and populate the doc-forge Project models.
|
||||
Utilities for loading and introspecting Python modules using Griffe.
|
||||
|
||||
This module provides the ``GriffeLoader`` class and helper utilities used to
|
||||
discover Python modules, introspect their structure, and convert the results
|
||||
into doc-forge documentation models.
|
||||
"""
|
||||
|
||||
import logging
|
||||
@@ -25,19 +28,27 @@ def discover_module_paths(
|
||||
project_root: Path | None = None,
|
||||
) -> List[str]:
|
||||
"""
|
||||
Discover all Python modules under a package via filesystem traversal.
|
||||
Discover Python modules within a package directory.
|
||||
|
||||
Rules:
|
||||
- Directory with __init__.py is treated as a package.
|
||||
- Any .py file is treated as a module.
|
||||
- All paths are converted to dotted module paths.
|
||||
The function scans the filesystem for ``.py`` files inside the specified
|
||||
package and converts them into dotted module import paths.
|
||||
|
||||
Discovery rules:
|
||||
|
||||
- Directories containing ``__init__.py`` are treated as packages.
|
||||
- Each ``.py`` file is treated as a module.
|
||||
- Results are returned as dotted import paths.
|
||||
|
||||
Args:
|
||||
module_name: The name of the package to discover.
|
||||
project_root: The root directory of the project. Defaults to current working directory.
|
||||
module_name: Top-level package name to discover modules from.
|
||||
project_root: Root directory used to resolve module paths. If not
|
||||
provided, the current working directory is used.
|
||||
|
||||
Returns:
|
||||
A sorted list of dotted module paths.
|
||||
A sorted list of unique dotted module import paths.
|
||||
|
||||
Raises:
|
||||
FileNotFoundError: If the specified package directory does not exist.
|
||||
"""
|
||||
|
||||
if project_root is None:
|
||||
@@ -64,12 +75,19 @@ def discover_module_paths(
|
||||
|
||||
class GriffeLoader:
|
||||
"""
|
||||
Loads Python modules and extracts documentation using the Griffe introspection engine.
|
||||
Load Python modules using Griffe and convert them into doc-forge models.
|
||||
|
||||
This loader uses the Griffe introspection engine to analyze Python source
|
||||
code and transform the extracted information into ``Project``, ``Module``,
|
||||
and ``DocObject`` instances used by doc-forge.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
"""
|
||||
Initialize the GriffeLoader.
|
||||
Initialize the Griffe-backed loader.
|
||||
|
||||
Creates an internal Griffe loader instance with dedicated collections
|
||||
for modules and source lines.
|
||||
"""
|
||||
self._loader = _GriffeLoader(
|
||||
modules_collection=ModulesCollection(),
|
||||
@@ -77,21 +95,32 @@ class GriffeLoader:
|
||||
)
|
||||
|
||||
def load_project(
|
||||
self,
|
||||
module_paths: List[str],
|
||||
project_name: Optional[str] = None,
|
||||
skip_import_errors: bool = None,
|
||||
self,
|
||||
module_paths: List[str],
|
||||
project_name: Optional[str] = None,
|
||||
skip_import_errors: bool = None,
|
||||
) -> Project:
|
||||
"""
|
||||
Load multiple modules and combine them into a single Project models.
|
||||
Load multiple modules and assemble them into a Project model.
|
||||
|
||||
Each module path is introspected and converted into a ``Module``
|
||||
instance. All modules are then aggregated into a single ``Project``
|
||||
object.
|
||||
|
||||
Args:
|
||||
module_paths: A list of dotted paths to the modules to load.
|
||||
project_name: Optional name for the project. Defaults to the first module name.
|
||||
skip_import_errors: If True, modules that fail to import will be skipped.
|
||||
module_paths: List of dotted module import paths to load.
|
||||
project_name: Optional override for the project name. Defaults
|
||||
to the top-level name of the first module.
|
||||
skip_import_errors: If True, modules that fail to load will be
|
||||
skipped instead of raising an error.
|
||||
|
||||
Returns:
|
||||
A Project instance containing the loaded modules.
|
||||
A populated ``Project`` instance containing the loaded modules.
|
||||
|
||||
Raises:
|
||||
ValueError: If no module paths are provided.
|
||||
ImportError: If a module fails to load and
|
||||
``skip_import_errors`` is False.
|
||||
"""
|
||||
if not module_paths:
|
||||
raise ValueError("At least one module path must be provided")
|
||||
@@ -116,13 +145,16 @@ class GriffeLoader:
|
||||
|
||||
def load_module(self, path: str) -> Module:
|
||||
"""
|
||||
Load a single module and convert its introspection data into the docforge models.
|
||||
Load and convert a single Python module.
|
||||
|
||||
The module is introspected using Griffe and then transformed into
|
||||
a doc-forge ``Module`` model.
|
||||
|
||||
Args:
|
||||
path: The dotted path of the module to load.
|
||||
path: Dotted import path of the module.
|
||||
|
||||
Returns:
|
||||
A Module instance.
|
||||
A populated ``Module`` instance.
|
||||
"""
|
||||
self._loader.load(path)
|
||||
griffe_module = self._loader.modules_collection[path]
|
||||
@@ -135,13 +167,16 @@ class GriffeLoader:
|
||||
|
||||
def _convert_module(self, obj: Object) -> Module:
|
||||
"""
|
||||
Convert a Griffe Object (module) into a docforge Module.
|
||||
Convert a Griffe module object into a doc-forge Module.
|
||||
|
||||
All public members of the module are recursively converted into
|
||||
``DocObject`` instances.
|
||||
|
||||
Args:
|
||||
obj: The Griffe Object representing the module.
|
||||
obj: Griffe object representing the module.
|
||||
|
||||
Returns:
|
||||
A populated Module instance.
|
||||
A populated ``Module`` model.
|
||||
"""
|
||||
module = Module(
|
||||
path=obj.path,
|
||||
@@ -158,13 +193,17 @@ class GriffeLoader:
|
||||
|
||||
def _convert_object(self, obj: Object) -> DocObject:
|
||||
"""
|
||||
Recursively convert a Griffe Object into a DocObject hierarchy.
|
||||
Convert a Griffe object into a doc-forge DocObject.
|
||||
|
||||
The conversion preserves the object's metadata such as name,
|
||||
kind, path, signature, and docstring. Child members are processed
|
||||
recursively.
|
||||
|
||||
Args:
|
||||
obj: The Griffe Object to convert.
|
||||
obj: Griffe object representing a documented Python object.
|
||||
|
||||
Returns:
|
||||
A DocObject instance.
|
||||
A ``DocObject`` instance representing the converted object.
|
||||
"""
|
||||
kind = obj.kind.value
|
||||
signature = self._safe_signature(obj)
|
||||
@@ -193,13 +232,13 @@ class GriffeLoader:
|
||||
|
||||
def _safe_docstring(self, obj: Object) -> Optional[str]:
|
||||
"""
|
||||
Safely retrieve the docstring value from a Griffe object.
|
||||
Safely extract a docstring from a Griffe object.
|
||||
|
||||
Args:
|
||||
obj: The Griffe Object to inspect.
|
||||
obj: Griffe object to inspect.
|
||||
|
||||
Returns:
|
||||
The raw docstring string, or None if missing or unresolvable.
|
||||
The raw docstring text if available, otherwise ``None``.
|
||||
"""
|
||||
try:
|
||||
return obj.docstring.value if obj.docstring else None
|
||||
@@ -208,13 +247,14 @@ class GriffeLoader:
|
||||
|
||||
def _safe_signature(self, obj: Object) -> Optional[str]:
|
||||
"""
|
||||
Safely retrieve the signature string from a Griffe object.
|
||||
Safely extract the signature of a Griffe object.
|
||||
|
||||
Args:
|
||||
obj: The Griffe Object to inspect.
|
||||
obj: Griffe object to inspect.
|
||||
|
||||
Returns:
|
||||
The string representation of the signature, or None.
|
||||
String representation of the object's signature if available,
|
||||
otherwise ``None``.
|
||||
"""
|
||||
try:
|
||||
if hasattr(obj, "signature") and obj.signature:
|
||||
|
||||
Reference in New Issue
Block a user