docs(lox-space): test Python reference docs

Author: helgee

crates/lox-space/.gitignore

@@ -73,3 +73,6 @@ docs/_build/
 
 # Pyenv
 .python-version
+
+# MkDocs documentation
+site/

crates/lox-space/docs/index.md

@@ -0,0 +1,25 @@
+<!--
+SPDX-FileCopyrightText: 2025 Helge Eichhorn <[email protected]>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
+
+::: lox_space.Time

crates/lox-space/lox_space.pyi

@@ -216,6 +216,7 @@ class TimeScale:
     def name(self) -> str: ...
 
 class Time:
+    """The Time class."""
     def __new__(
         cls,
         scale: Scale | TimeScale,

crates/lox-space/mkdocs.yml

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: 2025 Helge Eichhorn <[email protected]>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+site_name: My Docs
+theme:
+  name: material
+  palette:
+    scheme: slate
+    primary: indigo
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+
+        # Where to find your sources, see "Finding modules".
+        # paths: [src]
+
+        # Load object inventories to enable cross-references to other projects.
+        inventories:
+        - https://docs.python.org/3/objects.inv
+        # Also load inventories of your dependencies, generally served at
+        # https://docs-url-for-your-dependency/objects.inv.
+
+        options:
+
+          # DOCSTRINGS -------------------------------------------------------------
+          docstring_options:
+            # Discard first line of `__init__` method docstrings,
+            # useful when merging such docstrings into their parent class'.
+            ignore_init_summary: true
+
+          # Tables are generally too large, lists will fix this.
+          docstring_section_style: list
+
+          # CROSS-REFERENCES -------------------------------------------------------
+          # Enable relative crossrefs and scoped crossrefs, see Docstrings options.
+          # relative_crossrefs: true  # Sponsors only!
+          # scoped_crossrefs: true  # Sponsors only!
+
+          # Enable cross-references in signatures.
+          signature_crossrefs: true
+
+          # Unwrap actual types from `Annotated` type annotations.
+          unwrap_annotated: true
+
+          # MEMBERS ----------------------------------------------------------------
+          # Only render pulic symbols.
+          # filters: public  # Sponsors only!
+          # Comment the option otherwise to get the default filters.
+
+          # Show class inherited members.
+          inherited_members: true
+
+          # Render auto-generated summaries of attributes, functions, etc.
+          # at the start of each symbol's documentation.
+          summary: true
+
+          # HEADINGS ---------------------------------------------------------------
+          # For auto-generated pages, one module per page,
+          # make the module heading be the H1 heading of the page.
+          heading_level: 1
+
+          # Render headings for parameters, making them linkable.
+          parameter_headings: true
+
+          # Render headings for type parameters too.
+          type_parameter_headings: true
+
+          # Always show the heading for the symbol you render with `::: id`.
+          show_root_heading: true
+
+          # Only show the name of the symbols you inject render `::: id`.
+          show_root_full_path: false
+
+          # Show the type of symbol (class, function, etc.) in the heading.
+          show_symbol_type_heading: true
+
+          # Show the type of symbol (class, function, etc.) in the table of contents.
+          show_symbol_type_toc: true
+
+          # SIGNATURES -------------------------------------------------------------
+          # Format code to 80 + 10% margin (Black and Ruff defaults)
+          # in signatures and attribute value code blocks.
+          # Needs Black/Ruff installed.
+          line_length: 88
+
+          # Merge signature and docstring of `__init__` methods
+          # into their parent class signature and docstring.
+          merge_init_into_class: true
+
+          # Render signatures and attribute values in a separate code block,
+          # below the symbol heading.
+          separate_signature: true
+
+          # Show type annotations in signatures.
+          show_signature_annotations: true
+
+          # Show type parameters in signatures.
+          show_signature_type_parameters: true
+
+          # OTHER ------------------------------------------------------------------
+          # Show backlinks to other documentation sections within each symbol.
+          # backlinks: tree  # Sponsors only!
+
+          # Show base classes OR inheritance diagram.
+          show_bases: false
+          # show_inheritance_diagram: true  # Sponsors only!

crates/lox-space/pyproject.toml

@@ -15,6 +15,7 @@ dynamic = ["version"]
 
 [dependency-groups]
 dev = ["black", "ipython", "maturin", "pytest", "pytest-codspeed"]
+docs = ["mkdocs", "mkdocstrings[python]>=0.18", "mkdocs-material"]
 
 [build-system]
 requires = ["maturin>=1.3,<2.0"]
@@ -34,6 +35,7 @@ markers = [
 cache-keys = [
   { file = "pyproject.toml" },
   { file = "Cargo.toml" },
+  { file = "**/*.pyi" },
   { file = "**/*.rs" },
   { file = "../**/*.rs" },
 ]