docs: update docs and use api-autonav (#93)

* docs: use api-autonav

* more updates

* typing

* fixes

* more links

* fix union

* py38

* lint

* fix 38 again

Author: tlambert03

.pre-commit-config.yaml

@@ -9,7 +9,6 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
-      - id: check-docstring-first
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: pretty-format-json

docs/api/color.md

@@ -16,7 +16,7 @@ cmap = Colormap('viridis')
     `matplotlib.colors.Colormap` instance, you may call
     [`.to_mpl()`][cmap.Colormap.to_matplotlib].
 
-See the [Colormap API docs](../api/colormap.md) for details.
+See the [Colormap API docs][cmap.Colormap] for details.
 
 <!--
 With that object you can do things like:

docs/api/colormap.md

@@ -1,8 +1,13 @@
 # Colormaps
 
-The `cmap.Colormap` type represents a colormap.
+The [`cmap.Colormap`][cmap.Colormap] type represents a colormap.
 
-Also known as a LUT (look-up table), a colormap is a mapping from a scalar value to a color.  Colormaps are used in a variety of contexts, including image processing, data visualization, and scientific visualization.  The `cmap` library provides a [number of built-in colormaps](catalog/index.md), including all of the colormaps in matplotlib, napari, vispy, and more.
+Also known as a LUT (look-up table), a colormap is a mapping from a scalar value
+to a color.  Colormaps are used in a variety of contexts, including image
+processing, data visualization, and scientific visualization.  The `cmap`
+library provides a [number of built-in colormaps](catalog/index.md), including
+all of the colormaps in matplotlib, cmocean, colorbrewer, colorcet, crameri, and
+more.
 
 ```python
 from cmap import Colormap
@@ -15,7 +20,7 @@ cm = Colormap('viridis')
 
 The following objects can be interpreted as a colormap, and used as the first argument
 to the [`cmap.Colormap`][] constructor; `cmap` refers to these objects collectively as
-"`ColormapLike`".  Briefly, valid arguments are of type:
+["`ColormapLike`"][cmap.ColormapLike].  Briefly, valid arguments are of type:
 
 - [⬇️ `str`](#str)
 - [⬇️ `Iterable[ColorLike | tuple[float, ColorLike]]`](#iterablecolorlike-tuple)  *(see [`ColorLike`](colors.md#colorlike-objects))*
@@ -300,7 +305,7 @@ external visualization libraries.  To that end, `cmap.Colormap` provides
 `to_<libname>()` methods for a number of libraries:
 
 !!!tip
-    Some of these methods take additional arguments, see [Colormap API](api/colormap.md)
+    Some of these methods take additional arguments, see [Colormap API][cmap.Colormap]
     for details.
 
 - [matplotlib](https://matplotlib.org/)

docs/catalog/index.md

@@ -9,8 +9,10 @@ Namespaces are directories in the `src/cmap/data` folder.
 
 - If the colormap is part of known broader collection (e.g., `cet`, `cmocean`,
   `colorbrewer`, etc.), please check to see whether the collection already
-  exists in the `cmap/data` directory.  If so, please extend that collection.
-  If not, please create a new namespace and directory for that collection.
+  exists in the [`cmap/data`
+  directory](https://github.com/pyapp-kit/cmap/tree/main/src/cmap/data).  If so,
+  please extend that collection. If not, please create a new namespace and
+  directory for that collection.
 - If you would like to contribute a colormap that doesn't nicely fit into an
   broader collection of colormaps (regardless of whether that collection exists
   in `cmap`), please contribute to the `cmap/contrib` namespace.
@@ -24,7 +26,7 @@ Once you have picked a namespace:
    in the `record.json` file.  The key should be the name of the colormap, and
    the value should be an object with the following keys:
       - `data`: either a direct
-         [`ColormapLike` data](https://cmap-docs.readthedocs.io/en/stable/colormaps/#colormaplike-objects)
+         [`ColormapLike` data](colormaps.md#colormaplike-objects)
          entry, such as an array of RGB values; or a
          string pointing to the python-path of colormap data in the form of
          `cmap.data.<namespace>:<colormap>`.
@@ -57,8 +59,10 @@ Once you have picked a namespace:
     ]
     ```
 
-**It may be helpful to look at existing folders and files in the
-`cmap/data` directory for examples of how to structure the data.**
+!!!tip
+    It may be helpful to look at existing folders and files in the
+    [`cmap/data` directory](https://github.com/pyapp-kit/cmap/tree/main/src/cmap/data)
+    for examples of how to structure the data
 
 When opening a PR, please include a screenshot of the colormap, along
 with a brief description of the colormap design and its intended use.
@@ -74,7 +78,7 @@ with a brief description of the colormap design and its intended use.
 ## How can I add support for exporting to another colormap format?
 
 cmap [exports to a variety of known third-party colormap
-formats](https://cmap-docs.readthedocs.io/en/latest/colormaps/#usage-with-external-visualization-libraries).
+formats](colormaps.md#usage-with-external-visualization-libraries).
 
 If you are the author (or user) of a library that consumes colormaps, and you
 would like to have a `to_your_lib()` function in `cmap`, we welcome

docs/colormaps.md

@@ -1,14 +1,13 @@
 # Overview
 
-`cmap` is a work-in-progress colormap library for python, providing all of the
-colormaps in matplotlib, vispy, cmocean, (and more), with no dependencies beyond
-numpy.
+`cmap` is a colormap library for python, providing all of the colormaps in
+matplotlib, vispy, cmocean, (and more), with no dependencies beyond numpy.
 
 ## Purpose
 
 Mapping scalar values to colors is a very common procedure in scientific
 visualization; as such, many visualization libraries (e.g. matplotlib, vispy,
-napari, etc...) have some need for and some internal representation of colors
+pygfx, etc...) have some need for and some internal representation of colors
 and colormaps.
 
 !!!question "Don't we already have this?"
@@ -29,20 +28,21 @@ and colormaps.
    beyond numpy. (by "applying" here, we mean converting an array of scalar
    values to an array of RGBA values)
 3. Provide an API for converting colormaps to the native format for a variety of
-   third party libraries (currently including, matplotlib, napari, vispy, pygfx,
-   bokeh, plotly, altair, and more)
+   third party libraries (such as matplotlib, napari, vispy, pygfx,
+   bokeh, plotly, altair,
+   [and more](https://github.com/pyapp-kit/cmap/blob/main/src/cmap/_external.py))
 
 ## Colormaps
 
 For a complete list of available colormaps, see the [Colormaps
 catalog](catalog/index.md). You can also use the search bar at the top to search
 for a specific colormap.
 
-For details on using the `cmap.Colormap` object, see [Colormaps](colormaps.md).
+For details on using the [`cmap.Colormap`][cmap.Colormap] object, see [Colormaps](colormaps.md).
 
 ## Colors
 
-This library also offers a simple `cmap.Color` object.  It can cast a variety of
+This library also offers a simple [`cmap.Color`][cmap.Color] object.  It can cast a variety of
 inputs (including strings, tuples/lists, arrays, integers) to an RGBA color
 representation, and offers some basic conversions.  See [Colors](colors.md) for
 details

docs/faq.md

@@ -14,7 +14,6 @@ nav:
   - Colors: colors.md
   - Colormaps: colormaps.md
   - Colormap Catalog: catalog/
-  - API: api/
   - FAQ: faq.md
 
 theme:
@@ -68,7 +67,11 @@ hooks:
 plugins:
   - search:
       separator: '[\s\-\_,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
-  - autorefs
+  - autorefs:
+      resolve_closest: true
+  - api-autonav:
+      modules: ['src/cmap']
+      exclude: ['cmap.data']
   - literate-nav:
       implicit_index: true
       nav_file: SUMMARY.md
@@ -89,7 +92,7 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
-          import:
+          inventories:
             - https://docs.python.org/3/objects.inv
             - https://numpy.org/doc/stable/objects.inv
           options:
@@ -105,6 +108,14 @@ plugins:
             docstring_section_style: list
             merge_init_into_class: true
 
+            filters: ['(__call__|^[^_])']
+            heading_level: 1
+            parameter_headings: true
+            separate_signature: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            summary: true
+
 extra_css:
   - stylesheets/extra.css
 

docs/index.md

@@ -35,6 +35,7 @@ docs = [
     'imageio',
     'mkdocs-gen-files',
     'mkdocs-literate-nav',
+    'mkdocs-api-autonav',
     'mkdocs-material',
     'mkdocs-minify-plugin',
     'mkdocs',

mkdocs.yml

@@ -9,8 +9,8 @@
     __version__ = "uninstalled"
 
 
-from ._color import HSLA, HSVA, RGBA, RGBA8, Color
-from ._colormap import Colormap, ColorStops
+from ._color import HSLA, HSVA, RGBA, RGBA8, Color, ColorLike
+from ._colormap import Colormap, ColormapLike, ColorStop, ColorStops
 
 if TYPE_CHECKING:
     from ._catalog import CatalogItem
@@ -69,6 +69,9 @@ def resolve(self, name: str) -> str:
     "Catalog",
     "CatalogItem",
     "Color",
+    "ColorLike",
+    "ColorStop",
     "ColorStops",
     "Colormap",
+    "ColormapLike",
 ]