docs: use natsort for docs (#51)

* docs: use natsort for docs

* fix catalog sorting

* docs: use index and fix search

Author: tlambert03

docs/_gen_cmaps.py

@@ -1,8 +1,9 @@
 import json
 from pathlib import Path
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
 
 import mkdocs_gen_files
+import natsort
 import numpy as np
 
 if TYPE_CHECKING:
@@ -84,7 +85,8 @@
 
 
 def build_catalog(catalog: "_catalog.Catalog") -> None:
-    for name in catalog:
+    nav = mkdocs_gen_files.Nav()
+    for name in natsort.natsorted(catalog, alg=natsort.ns.IGNORECASE):
         if ":" not in name:
             continue
         try:
@@ -116,7 +118,9 @@ def build_catalog(catalog: "_catalog.Catalog") -> None:
         aliases = _make_aliases_md(_aliases) if _aliases else ""
 
         # write the actual markdown file
-        with mkdocs_gen_files.open(f"catalog/{category}/{name.lower()}.md", "w") as f:
+        doc_path = f"{category}/{name.lower()}.md"
+        nav[(category.title(), name)] = doc_path
+        with mkdocs_gen_files.open(f"catalog/{doc_path}", "w") as f:
             f.write(
                 TEMPLATE.format(
                     name=name,
@@ -130,9 +134,15 @@ def build_catalog(catalog: "_catalog.Catalog") -> None:
                 )
             )
 
+    # sort categories alphabetically
+    nav._data = dict(sorted(nav._data.items(), key=lambda x: x[0][0]))
+    with mkdocs_gen_files.open("catalog/SUMMARY.md", "w") as nav_file:
+        nav_file.writelines(["# SUMMARY { data-search-exclude }\n"])
+        nav_file.writelines(nav.build_literate_nav())
+
 
 def _make_aliases_md(aliases: list[str]) -> str:
     return "**Aliases**:  " + ", ".join(f"`{a}`" for a in aliases)
 
 
-build_catalog(cast("_catalog.Catalog", Colormap.catalog()))
+build_catalog(Colormap.catalog())

docs/_hooks.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Sequence, cast
 
+import natsort
 import numpy as np
 
 from cmap import Colormap, _util
@@ -24,7 +25,7 @@
 """
 CMAP_LINK = '<a href="{url}">' + CMAP_DIV + "</a>"
 DEV_MODE = "serve" in sys.argv
-SINERAMP = _util.sineramp((96, 512))[:, ::-1]
+SINERAMP = _util.sineramp((96, 826))[:, ::-1]
 
 
 def _to_img_tag(
@@ -34,7 +35,7 @@ def _to_img_tag(
     img: np.ndarray | None = None,
 ) -> str:
     """Return a base64-encoded <img> tag for the given colormap."""
-    _img = cm._repr_png_(width=256, height=1, img=img)
+    _img = cm._repr_png_(width=826, height=1, img=img)
     data = base64.b64encode(_img).decode("ascii")
     return (
         f'<img style="height: {height}" width="{width}" src="data:image/png;base64,'
@@ -91,7 +92,9 @@ def _cmap_catalog() -> str:
     """
     categories = set()
     lines = []
-    for cmap_name, details in sorted(CATALOG.items(), key=lambda x: x[0].lower()):
+    for cmap_name, details in natsort.natsorted(
+        CATALOG.items(), key=lambda x: x[0].lower()
+    ):
         if "alias" in details:
             continue
         category = details.get("category") or "Uncategorized"
@@ -185,7 +188,9 @@ def on_page_content(html: str, **kwargs: Any) -> str:
 
 def _write_cmap_redirects(site_dir: str) -> None:
     sd = Path(site_dir)
-    for cmap_name, details in sorted(CATALOG.items(), key=lambda x: x[0].lower()):
+    for cmap_name, details in natsort.natsorted(
+        CATALOG.items(), key=lambda x: x[0].lower()
+    ):
         if "alias" in details:
             cmap_name = cmap_name.replace(":", "-")
             real = Colormap(details["alias"])  # type: ignore
@@ -198,6 +203,6 @@ def _write_cmap_redirects(site_dir: str) -> None:
                 f.write(content)
 
 
-def on_post_build(config, **kwargs: Any) -> None:
+def on_post_build(config: dict, **kwargs: Any) -> None:
     """Copy the extra javascripts to the output directory."""
     _write_cmap_redirects(config["site_dir"])

mkdocs.yml

@@ -69,7 +69,9 @@ plugins:
   - search:
       separator: '[\s\-\_,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
   - autorefs
-  - literate-nav
+  - literate-nav:
+      implicit_index: true
+      nav_file: SUMMARY.md
   - gen-files:
       scripts:
         - docs/_gen_cmaps.py

pyproject.toml

@@ -31,15 +31,16 @@ globs = ["LICENSE/*"]
 # https://peps.python.org/pep-0621/#dependencies-optional-dependencies
 [project.optional-dependencies]
 docs = [
-    'mkdocs',
-    'mkdocs-material',
-    'mkdocstrings-python',
-    'mkdocs-minify-plugin',
-    'mkdocs-literate-nav',
-    'mkdocs-gen-files',
+    'colorcet',
     'colorspacious',
     'imageio',
-    'colorcet',
+    'mkdocs-gen-files',
+    'mkdocs-literate-nav',
+    'mkdocs-material',
+    'mkdocs-minify-plugin',
+    'mkdocs',
+    'mkdocstrings-python',
+    'natsort',
 ]
 test_min = ["pytest>=6.0"]
 test = ["cmap[test_min]", "pytest-cov"]
@@ -96,20 +97,20 @@ src = ["src"]
 [tool.ruff.lint]
 pydocstyle = { convention = "numpy" }
 select = [
-    "E",   # style errors
-    "F",   # flakes
-    "D",   # pydocstyle
+    "E",    # style errors
+    "F",    # flakes
+    "D",    # pydocstyle
     "D417", # Missing argument descriptions in Docstrings
-    "I",   # isort
-    "UP",  # pyupgrade
-    "S",   # bandit
-    "C4",  # flake8-comprehensions
-    "B",   # flake8-bugbear
-    "ISC", # implicit-str-concat
-    "TID", # tidy-imports
-    "RUF", # ruff-specific rules
-    "TCH", # flake8-type-checking
-    "TID", # flake8-tidy-imports
+    "I",    # isort
+    "UP",   # pyupgrade
+    "S",    # bandit
+    "C4",   # flake8-comprehensions
+    "B",    # flake8-bugbear
+    "ISC",  # implicit-str-concat
+    "TID",  # tidy-imports
+    "RUF",  # ruff-specific rules
+    "TCH",  # flake8-type-checking
+    "TID",  # flake8-tidy-imports
 ]
 ignore = [
     "D100", # Missing docstring in public module