Fix mkdocs lib path and complete public API docstrings

lib/palettes/__init__.py

@@ -19,6 +19,8 @@
         :class:`~palettes.wheel.WheelPalette`.
 """
 
+__all__ = ["WIN16", "get_palette", "Palette", "MappedPalette"]
+
 WIN16 = {
     0x000000: "Black",
     0x000080: "Navy",
@@ -85,6 +87,15 @@ class Palette:
     """
 
     def __init__(self, name="", color_depth=16, swapped=False, cached=False):
+        """Create a palette from the default Windows 16-color name table.
+
+        Args:
+            name: Optional label stored in :attr:`name`.
+            color_depth: Output format for :meth:`__getitem__`: ``4``, ``8``,
+                ``16``, or ``24``.
+            swapped: If ``True``, byte-swap 16-bit colors.
+            cached: If ``True``, memoize computed index colors.
+        """
         self._name = name
         self._color_depth = color_depth
         self._swapped = swapped
@@ -296,6 +307,14 @@ class MappedPalette(Palette):
     """
 
     def __init__(self, name, color_depth, swapped, color_map):
+        """Create a palette from a flat RGB byte map.
+
+        Args:
+            name: Optional label stored in :attr:`name`.
+            color_depth: Output format for :meth:`Palette.__getitem__`.
+            swapped: Byte-swap 16-bit colors when ``True``.
+            color_map: ``bytes`` or buffer of RGB triplets.
+        """
         self._color_map = color_map
         self._length = len(color_map) // 3
         super().__init__(name, color_depth, swapped)

lib/palettes/cube.py

@@ -32,6 +32,16 @@ class CubePalette(_Palette):
     """
 
     def __init__(self, name="", color_depth=16, swapped=False, cached=True, size=5):
+        """Create an evenly spaced RGB cube palette.
+
+        Args:
+            name: Prefix for :attr:`~palettes.Palette.name` (length suffix
+                is added).
+            color_depth: Output format; see :class:`~palettes.Palette`.
+            swapped: Byte-swap 16-bit colors when ``True``.
+            cached: Memoize index lookups when ``True`` (default).
+            size: Cube edge length. Must be ``2``, ``3``, ``4``, or ``5``.
+        """
         self._size = size
         self._length = size**3
         self._values = [round(i * (255 / (size - 1)) + 0.25) for i in range(size)]

lib/palettes/material_design.py

@@ -52,6 +52,16 @@ class MDPalette(MappedPalette):
     _accents = ["A100", "A200", "A400", "A700"]
 
     def __init__(self, name="", color_depth=16, swapped=False, color_map=COLORS):
+        """Create a Material Design swatch palette.
+
+        Args:
+            name: Label for :attr:`~palettes.Palette.name`; defaults to
+                ``"MaterialDesign"`` when empty.
+            color_depth: Output format; see :class:`~palettes.Palette`.
+            swapped: Byte-swap 16-bit colors when ``True``.
+            color_map: RGB byte map; defaults to the built-in Material Design
+                table.
+        """
         super().__init__(name, color_depth, swapped, color_map)
         self._name = name if name else "MaterialDesign"
 

lib/palettes/wheel.py

@@ -50,6 +50,24 @@ def __init__(
         saturation=1.0,
         value=None,
     ):
+        """Create a wheel or fixed-saturation HSV ramp palette.
+
+        Args:
+            name: Prefix for :attr:`~palettes.Palette.name` (length suffix
+                is added).
+            color_depth: Output format; see :class:`~palettes.Palette`.
+            swapped: Byte-swap 16-bit colors when ``True``.
+            cached: Memoize index lookups when ``True`` (default).
+            length: Number of colors in the wheel (default ``256``).
+            saturation: HSV saturation in ``0.0``–``1.0``, or ``None`` for
+                classic wheel mode.
+            value: HSV value in ``0.0``–``1.0``, or ``None`` for classic
+                wheel mode.
+
+        Raises:
+            ValueError: If ``saturation`` or ``value`` is outside ``0``–``1``
+                in HSV mode.
+        """
         self._length = length
 
         if saturation is None and value is None:

mkdocs.yml

@@ -41,7 +41,7 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
-          paths: [src]
+          paths: [lib]
           options:
             show_source: false
             show_root_heading: true

scripts/mkdocs_gen_ref_pages.py

@@ -1,12 +1,15 @@
-"""Generate mkdocstrings API reference stubs and navigation for palettes."""
+"""Generate mkdocstrings API reference stubs and navigation for palettes.
+
+Walks ``lib/palettes/`` (package lives under ``lib/``, not ``src/``).
+"""
 
 from pathlib import Path
 
 import mkdocs_gen_files
 
 nav = mkdocs_gen_files.Nav()
 root = Path(__file__).parent.parent
-src = root / "src"
+src = root / "lib"
 reference = Path("reference")
 
 for path in sorted((src / "palettes").rglob("*.py")):
@@ -22,7 +25,7 @@
         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__":
+    if not parts or parts[-1] == "__main__" or any(part.startswith("_") for part in parts):
         continue
 
     nav[parts] = doc_path.as_posix()