diff --git a/lib/palettes/__init__.py b/lib/palettes/__init__.py index 1e0e501..f07739c 100644 --- a/lib/palettes/__init__.py +++ b/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) diff --git a/lib/palettes/cube.py b/lib/palettes/cube.py index 139b849..01e4188 100644 --- a/lib/palettes/cube.py +++ b/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)] diff --git a/lib/palettes/material_design.py b/lib/palettes/material_design.py index 5c0d1ed..2ca8774 100644 --- a/lib/palettes/material_design.py +++ b/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" diff --git a/lib/palettes/wheel.py b/lib/palettes/wheel.py index e746d32..7c6e443 100644 --- a/lib/palettes/wheel.py +++ b/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: diff --git a/mkdocs.yml b/mkdocs.yml index f42dc80..03cbe37 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,7 +41,7 @@ plugins: - mkdocstrings: handlers: python: - paths: [src] + paths: [lib] options: show_source: false show_root_heading: true diff --git a/scripts/mkdocs_gen_ref_pages.py b/scripts/mkdocs_gen_ref_pages.py index 112ef00..7dca180 100644 --- a/scripts/mkdocs_gen_ref_pages.py +++ b/scripts/mkdocs_gen_ref_pages.py @@ -1,4 +1,7 @@ -"""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 @@ -6,7 +9,7 @@ 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()