Split doc

.gitignore

@@ -66,8 +66,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/apidoc/modules.rst
 docs/apidoc/figanos*.rst
+docs/apidoc/modules.rst
 
 # PyBuilder
 target/

.pre-commit-config.yaml

@@ -48,7 +48,8 @@ repos:
     hooks:
       - id: ruff
         args: [ '--fix' ]
-      # - id: ruff-format
+      - id: ruff-format
+        exclude: ^src/figanos
   - repo: https://github.com/pycqa/flake8
     rev: 7.1.1
     hooks:
@@ -66,7 +67,10 @@ repos:
     hooks:
       - id: nbstripout
         files: '.ipynb'
-        args: [ '--extra-keys=metadata.kernelspec' ]
+        args: [
+          '--extra-keys="metadata.kernelspec"',
+          '--keep-metadata-keys="cell.metadata.nbsphinx"'
+        ]
   - repo: https://github.com/adrienverge/yamllint.git
     rev: v1.35.1
     hooks:

CHANGELOG.rst

@@ -4,7 +4,7 @@ Changelog
 
 `Unreleased <https://github.com/Ouranosinc/figanos>`_ (latest)
 --------------------------------------------------------------
-Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Marco Braun (:user:`vindelico`), Pascal Bourgault (:user:`aulemahal`), Sarah-Claude Bourdeau-Goulet (:user:`Sarahclaude`), Éric Dupuis (:user:`coxipi`), Juliette Lavoie (:user:`juliettelavoie`)
+Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Marco Braun (:user:`vindelico`), Pascal Bourgault (:user:`aulemahal`), Sarah-Claude Bourdeau-Goulet (:user:`Sarahclaude`), Éric Dupuis (:user:`coxipi`), Juliette Lavoie (:user:`juliettelavoie`).
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -18,6 +18,8 @@ New features and enhancements
 * A new optional way to organize points in a ``fg.taylordiagram``  with  `colors_key`, `markers_key`  : DataArrays with a common dimension value or a common attribute are grouped with the same color/marker (:pull:`214`).
 * Heatmap (``fg.matplotlib.heatmap``) now supports `row,col` arguments in `plot_kw`, allowing to plot a grid of heatmaps. (:issue:`208`, :pull:`219`).
 * New function ``fg.matplotlib.triheatmap`` (:pull:`199`).
+* Reorganized the documentation and add gallery (:issue:`278`, :issue:`274`, :issue:`202`, :pull:`279`).
+* Added a new `pooch`-based mechanism for fetching and caching testing data used in the notebooks (``fg.pitou().fetch()``). (:pull:`279`).
 
 Breaking changes
 ^^^^^^^^^^^^^^^^

docs/conf.py

@@ -68,7 +68,7 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a dictionary of suffix: filetype
-source_suffix = {'.rst': 'restructuredtext'}
+source_suffix = {".rst": "restructuredtext"}
 
 # The master toctree document.
 master_doc = "index"
@@ -129,8 +129,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 if not os.path.exists("_static"):
     os.makedirs("_static")
-html_static_path = ['_static']
-
+html_static_path = ["_static"]
 
 # -- Options for HTMLHelp output ---------------------------------------
 

docs/gallery.rst

@@ -0,0 +1,90 @@
+Gallery
+========
+
+Here is a gallery of examples of `figanos`.
+Go to the examples to see how to generate these figures.
+
+Timeseries
+^^^^^^^^^^^
+Full code in the `Timeseries notebook <notebooks/figanos_timeseries.ipynb>`_.
+
+.. image:: _static/_gallery/basic_timeseries.png
+    :width: 40%
+    :target: notebooks/figanos_timeseries.html#Basic-timeseries
+
+.. image:: _static/_gallery/ensemble_timeseries.png
+    :width: 40%
+    :target: notebooks/figanos_timeseries.html#Ensembles
+
+Maps
+^^^^
+Full code in the `Maps notebook <notebooks/figanos_maps.ipynb>`_.
+
+.. image:: _static/_gallery/basic_map.png
+    :width: 30%
+    :target: notebooks/figanos_maps.html#Gridded-Data-on-Maps
+
+.. image:: _static/_gallery/station_map.png
+    :width: 30%
+    :target: notebooks/figanos_maps.html#Station-Data-on-Maps
+
+.. image:: _static/_gallery/station+grid_map.png
+    :width: 30%
+    :target: notebooks/figanos_maps.html#Station-Data-on-Maps
+
+.. image:: _static/_gallery/hatch_map.png
+    :width: 30%
+    :target: notebooks/figanos_maps.html#Hatching-on-Maps
+
+.. image:: _static/_gallery/gdf_map.png
+    :width: 30%
+    :target: notebooks/figanos_maps.html#GeoDataFrame-on-Maps
+
+.. image:: _static/_gallery/gdf2_map.png
+    :width: 30%
+    :target: notebooks/figanos_maps.html#GeoDataFrame-on-Maps
+
+Miscellaneous
+^^^^^^^^^^^^^
+Full code in the `Miscellaneous notebook <notebooks/figanos_misc.ipynb>`_.
+
+.. image:: _static/_gallery/stripes.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Climate-Stripes
+
+.. image:: _static/_gallery/violin.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Violin-Plots
+
+.. image:: _static/_gallery/heatmap.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Heatmaps
+
+.. image:: _static/_gallery/triangle1.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Triangle-heatmaps
+
+.. image:: _static/_gallery/triangle2.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Triangle-Heatmaps
+
+.. image:: _static/_gallery/taylor.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Taylor-Diagrams
+
+.. image:: _static/_gallery/partition.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Partition-plots
+
+.. image:: _static/_gallery/logo.png
+    :width: 30%
+    :target: notebooks/figanos_misc.html#Logos
+
+Multiple plots
+^^^^^^^^^^^^^^
+
+Full code in the `Multiple plots notebook <notebooks/figanos_multiplots.ipynb>`_.
+
+.. image:: _static/_gallery/multiple.png
+    :width: 50%
+    :target: notebooks/figanos_multiplots.html#Maps

docs/index.rst

@@ -3,8 +3,23 @@ Welcome to figanos's documentation!
 
 Figanos: Tool to create **fig**\ ures\  in\  the Our\ **anos**\  style.
 
+Overview
+^^^^^^^^
+
+Figanos is a dictionary-based function interface that wraps `Matplotlib <https://matplotlib.org>`_ and `Xarray <https://docs.xarray.dev/en/stable/>`_ plotting functions to create common climate data plots. Its inputs are most commonly xarray DataArrays or Datasets, and it is best used when these arrays are the output of workflows incorporating `Xscen <https://github.com/Ouranosinc/xscen>`_ and/or `Xclim <https://xclim.readthedocs.io/en/stable/>`_. Style-wise, the plots follow the general guidelines offered by the `IPCC visual style guide 2022 <https://www.ipcc.ch/site/assets/uploads/2022/09/IPCC_AR6_WGI_VisualStyleGuide_2022.pdf>`_, but aim to create a look that could be distinctively associated with `Ouranos <https://www.ouranos.ca/en>`_.
+
+
+The following features are included in the package:
+
+* Automatically recognizes some common data structures (e.g. climate ensembles) using variable and coordinate names and creates the appropriate plots.
+* Automatically links attributes from xarray objects to plot elements (title, axes), with customization options.
+* Automatically assigns colors to some common variables and, following the IPCC visual guidelines.
+* Provides options to visually enhance the plots, and includes a default style to ensure coherence when creating multiple plots.
+* Returns a `matplotlib axes object <https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes>`_ that is fully customizeable through matplotlib functions and methods.
+
+
 Need help?
-==========
+^^^^^^^^^^
 * Ouranos employees can ask questions on the Ouranos private StackOverflow where you can tag subjects and people. (https://stackoverflow.com/c/ouranos/questions ).
 * Potential bugs in figanos can be reported as an issue here: https://github.com/Ouranosinc/figanos/issues .
 * Problems with data on Ouranos' servers can be reported as an issue here: https://github.com/Ouranosinc/miranda/issues
@@ -16,9 +31,8 @@ Need help?
 
    installation
    usage
-   notebooks/figanos_docs
-   notebooks/figanos_colours
-   notebooks/figanos_multiplots
+   gallery
+   notebooks/index
    api
    contributing
    releasing