Feat/cheat sheet

.gitignore

@@ -59,3 +59,13 @@ ultraplot/_version.py
 
 # Nox build directories
 .nox/*
+
+# Cheatsheet build output: the icons, the sheets, and the copies the docs use.
+# All are generated by tools/cheatsheet/build.py, and regenerated during the
+# docs build, so only the sources belong in the repository.
+tools/cheatsheet/assets/
+docs/_static/plot_types/
+ultraplot_cheatsheet*.pdf
+ultraplot_cheatsheet*.png
+ultraplot_plot_types*.pdf
+ultraplot_plot_types*.png

docs/_scripts/build_plot_types.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+Regenerate the visual plot-type index before a documentation build.
+
+Run from ``conf.py`` the same way ``fetch_releases.py`` is: the page and its
+thumbnails are generated artefacts, so a clean checkout builds them rather than
+carrying 60-odd PNGs in the repository. Rendering is skipped when the icons are
+already present, so a local rebuild costs nothing.
+"""
+
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(os.path.dirname(HERE))
+GENERATOR = os.path.join(ROOT, "tools", "cheatsheet")
+
+sys.path.insert(0, GENERATOR)
+
+
+def main():
+    try:
+        import docs_index
+    except ImportError as error:  # the tools folder is not shipped in sdists
+        print(f"plot-type index skipped: {error}")
+        return
+    try:
+        docs_index.main()
+    except Exception as error:  # never fail the docs build over a thumbnail
+        print(f"plot-type index skipped: {type(error).__name__}: {error}")
+
+
+if __name__ == "__main__":
+    main()

docs/conf.py

@@ -65,6 +65,8 @@ def __getattr__(self, name):
 }
 if not FAST_PREVIEW:
     run([sys.executable, "_scripts/fetch_releases.py"], check=False)
+    # Visual plot-type index: thumbnails plus the page that arranges them.
+    run([sys.executable, "_scripts/build_plot_types.py"], check=False)
 
 # Docs theme selector. Default to Shibuya, but keep env override for A/B checks.
 DOCS_THEME = os.environ.get("UPLT_DOCS_THEME", "shibuya").strip().lower()

docs/index.rst

@@ -129,6 +129,7 @@ For more details, check the full :doc:`User guide <usage>` and :doc:`API Referen
    :hidden:
 
    basics
+   plot_types
    subplots
    cartesian
    networks