Documentation structure improvement

CHANGELOG.rst

@@ -224,7 +224,7 @@ New Features
 
   The handler receives the clicked panel, its state, the chosen theme, and bound
   ``exportPNG`` / ``exportCanvas`` / ``downloadPNG`` / ``copyPNG`` / ``toast``
-  helpers. See :doc:`exporting` for the full reference.
+  helpers. See :doc:`/user_guide/exporting` for the full reference.
 - The 2-D hover readout now also names the **value** of the pixel under the
   cursor — ``v:<value>`` for a colourmapped image, ``rgb:r,g,b`` for a true-colour
   one — alongside the existing physical and pixel coordinates. It is exact:

docs/api/index.rst

@@ -74,7 +74,7 @@ directly to a class or function.
 
       The :class:`~anyplotlib.CallbackRegistry` event engine and the
       flat :class:`~anyplotlib.Event` dataclass.
-      See :doc:`../events` for the full event-system guide.
+      See :doc:`/user_guide/events` for the full event-system guide.
 
 
 Figure

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst

docs/dev/index.rst

@@ -6,6 +6,12 @@ This guide covers everything you need to contribute to anyplotlib —
 from setting up your environment to writing documentation and interactive
 gallery examples.
 
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   benchmarking
+
 .. contents:: On this page
    :local:
    :depth: 2
@@ -123,15 +129,20 @@ extensions:
 Adding a new RST page
 ---------------------
 
-1. Create ``docs/my_page.rst``.
-2. Add it to the ``toctree`` in ``docs/index.rst``::
+1. Create the RST page, e.g. ``docs/user_guide/my_page.rst``.
+2. Add it to the ``toctree`` of its section's index page (e.g.
+   ``docs/user_guide/index.rst``)::
 
       .. toctree::
          :hidden:
          :maxdepth: 2
 
          my_page
 
+   The top navigation bar is rendered from the ``toctree`` in
+   ``docs/index.rst``; its five entries are the top-bar sections
+   (User guide, Examples, References, Contribute, Releases).
+
 Embedding a static figure in RST
 ---------------------------------
 

docs/index.rst

@@ -38,7 +38,7 @@ blitting instead of SVG.
    :gutter: 2
 
    .. grid-item-card::
-      :link: getting_started
+      :link: user_guide/getting_started
       :link-type: doc
 
       :octicon:`rocket;2em;sd-text-info` Getting Started
@@ -79,7 +79,7 @@ blitting instead of SVG.
       plus an honest look at current limitations.
 
    .. grid-item-card::
-      :link: benchmarking
+      :link: dev/benchmarking
       :link-type: doc
 
       :octicon:`tools;2em;sd-text-info` Benchmarking
@@ -90,7 +90,7 @@ blitting instead of SVG.
       comparisons hardware-agnostic.
 
    .. grid-item-card::
-      :link: events
+      :link: user_guide/events
       :link-type: doc
 
       :octicon:`zap;2em;sd-text-info` Event System
@@ -101,7 +101,7 @@ blitting instead of SVG.
       pygfx and an implementation-status table.
 
    .. grid-item-card::
-      :link: exporting
+      :link: user_guide/exporting
       :link-type: doc
 
       :octicon:`download;2em;sd-text-info` Exporting Images
@@ -111,6 +111,16 @@ blitting instead of SVG.
       light/dark output, native-resolution export, ``Figure.savefig``, and
       adding your own save formats from an embedding application.
 
+   .. grid-item-card::
+      :link: changelog
+      :link-type: doc
+
+      :octicon:`history;2em;sd-text-info` Release Notes
+      ^^^
+
+      Notable changes in each release — new features, API and behaviour
+      changes, deprecations, and bug fixes.
+
    .. grid-item-card::
       :link: dev/index
       :link-type: doc
@@ -125,15 +135,11 @@ blitting instead of SVG.
    :hidden:
    :maxdepth: 2
 
-   getting_started
-   events
-   embedding
-   exporting
-   api/index
-   auto_examples/index
-   Performance <auto_examples/Benchmarks/plot_benchmark_comparison>
-   benchmarking
-   dev/index
+   User guide <user_guide/index>
+   Examples <auto_examples/index>
+   References <api/index>
+   Contribute <dev/index>
+   Releases <changelog>
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/events.rst → docs/user_guide/events.rst

@@ -767,8 +767,8 @@ API Reference
       Low-level registry: ``connect``, ``disconnect``, ``fire``,
       ``pause_events``, ``hold_events``.
 
-   :doc:`api/callbacks`
+   :doc:`/api/callbacks`
       Autogenerated API documentation for both classes.
 
-   :doc:`auto_examples/index`
+   :doc:`/auto_examples/index`
       Gallery of interactive examples using ``add_event_handler``.

docs/getting_started.rst → docs/user_guide/getting_started.rst

@@ -135,7 +135,7 @@ All line properties can be changed after creation without recreating the panel::
   static marker collections at explicit data coordinates.
 
 See :class:`~anyplotlib.Plot1D` for the full API reference, and
-the :doc:`auto_examples/index` gallery (e.g. *1D Line Styles* or *1D Spectra*)
+the :doc:`/auto_examples/index` gallery (e.g. *1D Line Styles* or *1D Spectra*)
 for worked examples.
 
 2-D image
@@ -201,5 +201,5 @@ Bar chart
     bar = ax.bar(values, x_labels=months, color="#4fc3f7", show_values=True)
     bar  # display in a Jupyter cell
 
-For more elaborate usage, see the :doc:`auto_examples/index` gallery or
-the :doc:`api/index`.
+For more elaborate usage, see the :doc:`/auto_examples/index` gallery or
+the :doc:`/api/index`.

docs/user_guide/index.rst

@@ -0,0 +1,62 @@
+==============
+User Guide
+==============
+
+The user guide walks through using anyplotlib in a Jupyter notebook or
+JupyterLab — from installation to interactive event handling and exporting
+figures.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   getting_started
+   events
+   embedding
+   exporting
+
+.. grid:: 2
+   :gutter: 2
+
+   .. grid-item-card::
+      :link: getting_started
+      :link-type: doc
+
+      :octicon:`rocket;2em;sd-text-info` Getting Started
+      ^^^
+
+      Installation and your first interactive figure in a Jupyter
+      notebook — creating a ``Figure``, calling methods on ``Axes``,
+      and displaying it.
+
+   .. grid-item-card::
+      :link: events
+      :link-type: doc
+
+      :octicon:`zap;2em;sd-text-info` Event System
+      ^^^
+
+      Interactive event handling — ``pointer_down``, ``pointer_settled``,
+      ``key_down``, and more. Includes a comparison with Matplotlib and
+      pygfx and an implementation-status table.
+
+   .. grid-item-card::
+      :link: embedding
+      :link-type: doc
+
+      :octicon:`package;2em;sd-text-info` Embedding
+      ^^^
+
+      Using anyplotlib outside Jupyter — Electron apps, web pages, and
+      live Python↔JS synchronisation from a standalone Python process.
+
+   .. grid-item-card::
+      :link: exporting
+      :link-type: doc
+
+      :octicon:`download;2em;sd-text-info` Exporting Images
+      ^^^
+
+      Saving and copying figures as PNG — the right-click menu, ``Ctrl+C``,
+      light/dark output, native-resolution export, ``Figure.savefig``, and
+      adding your own save formats from an embedding application.