Vishesh 'ironeagle' Bangotra
b6306baafc
# 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>
80 lines
2.2 KiB
Python
80 lines
2.2 KiB
Python
"""
|
|
Documentation model representing a Python module or package.
|
|
|
|
This module defines the ``Module`` class used in the doc-forge documentation
|
|
model. A ``Module`` acts as a container for top-level documented objects
|
|
(classes, functions, variables, and other members) discovered during
|
|
introspection.
|
|
"""
|
|
|
|
from typing import Dict, Iterable, Optional
|
|
|
|
from docforge.models.object import DocObject
|
|
|
|
|
|
class Module:
|
|
"""
|
|
Representation of a documented Python module or package.
|
|
|
|
A ``Module`` stores metadata about the module itself and maintains a
|
|
collection of top-level documentation objects discovered during
|
|
introspection.
|
|
|
|
Attributes:
|
|
path: Dotted import path of the module.
|
|
docstring: Module-level documentation string, if present.
|
|
members: Mapping of object names to their corresponding
|
|
``DocObject`` representations.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
path: str,
|
|
docstring: Optional[str] = None,
|
|
) -> None:
|
|
"""
|
|
Initialize a Module instance.
|
|
|
|
Args:
|
|
path: Dotted import path identifying the module.
|
|
docstring: Module-level documentation text, if available.
|
|
"""
|
|
self.path = path
|
|
self.docstring = docstring
|
|
self.members: Dict[str, DocObject] = {}
|
|
|
|
def add_object(self, obj: DocObject) -> None:
|
|
"""
|
|
Add a documented object to the module.
|
|
|
|
Args:
|
|
obj: Documentation object to register as a top-level
|
|
member of the module.
|
|
"""
|
|
self.members[obj.name] = obj
|
|
|
|
def get_object(self, name: str) -> DocObject:
|
|
"""
|
|
Retrieve a documented object by name.
|
|
|
|
Args:
|
|
name: Name of the object to retrieve.
|
|
|
|
Returns:
|
|
The corresponding ``DocObject`` instance.
|
|
|
|
Raises:
|
|
KeyError: If no object with the given name exists.
|
|
"""
|
|
return self.members[name]
|
|
|
|
def get_all_objects(self) -> Iterable[DocObject]:
|
|
"""
|
|
Return all top-level documentation objects in the module.
|
|
|
|
Returns:
|
|
An iterable of ``DocObject`` instances representing the
|
|
module's public members.
|
|
"""
|
|
return self.members.values()
|