Add keywords, move indicators API to its own page (#1502)

### What kind of change does this PR introduce? * Changes how the "keyword" attribute is inherited between indicators to inherit by concatenating. * Add basic keywords to all subclasses * Move the indicators API to its own page to lower loading times (it's still slow, but a lot more bearable IMO) ### Does this PR introduce a breaking change? No.
Ouranosinc · Oct 16, 2023 · 21388ff · 21388ff
2 parents e6fcaeb + b9f9874
commit 21388ff
Show file tree

Hide file tree

Showing 12 changed files with 74 additions and 48 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -46,6 +46,7 @@ Internal changes
 * The `pkg_resources` library has been replaced for the `packaging` library when version comparisons have been performed, and a few warning messages have been silenced in the testing suite. (:issue:`1489`, :pull:`1490`).
 * New ``xclim.testing.helpers.assert_lazy`` context manager to assert the laziness of code blocks. (:pull:`1484`).
 * Added a fix for the deprecation warnings that `importlib.resources` throws, made backwards-compatible for Python3.8 with `importlib_resources` backport. (:pull:`1485`).
+* Added basic keywords on most indicators for easier searching in the docs. Extracted climate indicators API to its own page for faster loaing. (:pull:`1502`, :issue:`1433`).
 
 v0.45.0 (2023-09-05)
 --------------------

diff --git a/docs/_static/indsearch.js b/docs/_static/indsearch.js
@@ -67,7 +67,7 @@ function indTemplate(ind) {
     <div class="indElem" id="${ind.id}">
       <div class="indHeader">
         <b class="indTitle">${ind.title}</b>
-        <a class="reference_internal indName" href="api.html#xclim.indicators.${ind.module}.${ind.name}" title="${ind.name}">
+        <a class="reference_internal indName" href="api_indicators.html#xclim.indicators.${ind.module}.${ind.name}" title="${ind.name}">
           <code>${ind.module}.${ind.name}</code>
         </a>
       </div>

diff --git a/docs/api.rst b/docs/api.rst
@@ -10,51 +10,10 @@ API
 Indicators
 ==========
 
-Indicators are the main tool xclim provides to compute climate indices. In contrast
-to the function defined in `xclim.indices`, Indicators add a layer of health checks
-and metadata handling. Indicator objects are split into realms : atmos, land and seaIce.
+.. toctree::
+   :maxdepth: 1
 
-Virtual modules are also inserted here. A normal installation of xclim comes with three virtual modules:
-
- - :py:mod:`xclim.indicators.cf`, Indicators defined in `cf-index-meta`.
- - :py:mod:`xclim.indicators.icclim`, Indicators defined by ECAD, as found in  python package Icclim.
- - :py:mod:`xclim.indicators.anuclim`, Indicators of the Australian National University's Fenner School of Environment and Society.
-
-Climate Indicators API
-----------------------
-
-.. automodule:: xclim.indicators.atmos
-   :members:
-   :undoc-members:
-   :imported-members:
-
-.. automodule:: xclim.indicators.land
-   :members:
-   :undoc-members:
-   :imported-members:
-
-.. automodule:: xclim.indicators.seaIce
-   :members:
-   :undoc-members:
-   :imported-members:
-
-Virtual Indicator Submodules
-----------------------------
-
-.. automodule:: xclim.indicators.cf
-   :members:
-   :imported-members:
-   :undoc-members:
-
-.. automodule:: xclim.indicators.icclim
-   :members:
-   :imported-members:
-   :undoc-members:
-
-.. automodule:: xclim.indicators.anuclim
-   :members:
-   :imported-members:
-   :undoc-members:
+   api_indicators
 
 Indices
 =======

diff --git a/docs/api_indicators.rst b/docs/api_indicators.rst
@@ -0,0 +1,45 @@
+Indicators are the main tool xclim provides to compute climate indices. In contrast
+to the function defined in `xclim.indices`, Indicators add a layer of health checks
+and metadata handling. Indicator objects are split into realms : atmos, land and seaIce.
+
+Virtual modules are also inserted here. A normal installation of xclim comes with three virtual modules:
+
+ - :py:mod:`xclim.indicators.cf`, Indicators defined in `cf-index-meta`.
+ - :py:mod:`xclim.indicators.icclim`, Indicators defined by ECAD, as found in  python package Icclim.
+ - :py:mod:`xclim.indicators.anuclim`, Indicators of the Australian National University's Fenner School of Environment and Society.
+
+Climate Indicators API
+----------------------
+
+.. automodule:: xclim.indicators.atmos
+   :members:
+   :undoc-members:
+   :imported-members:
+
+.. automodule:: xclim.indicators.land
+   :members:
+   :undoc-members:
+   :imported-members:
+
+.. automodule:: xclim.indicators.seaIce
+   :members:
+   :undoc-members:
+   :imported-members:
+
+Virtual Indicator Submodules
+----------------------------
+
+.. automodule:: xclim.indicators.cf
+   :members:
+   :imported-members:
+   :undoc-members:
+
+.. automodule:: xclim.indicators.icclim
+   :members:
+   :imported-members:
+   :undoc-members:
+
+.. automodule:: xclim.indicators.anuclim
+   :members:
+   :imported-members:
+   :undoc-members:
diff --git a/tests/test_formatting.py b/tests/test_formatting.py
@@ -30,7 +30,7 @@ def test_indicator_docstring():
         doc[5]
         == "Based on indice :py:func:`~xclim.indices._multivariate.heat_wave_frequency`."
     )
-    assert doc[6] == "Keywords : health,."
+    assert doc[6] == "Keywords : temperature health,."
     assert doc[12] == "  Default : `ds.tasmin`. [Required units : [temperature]]"
     assert (
         doc[41]
@@ -42,7 +42,7 @@ def test_indicator_docstring():
     )
 
     doc = degree_days_exceedance_date.__doc__.split("\n")
-    assert doc[20] == "  Default : >. "
+    assert doc[21] == "  Default : >. "
 
 
 def test_update_xclim_history(atmosds):

diff --git a/xclim/core/indicator.py b/xclim/core/indicator.py
@@ -462,9 +462,12 @@ def __new__(cls, **kwds):
         # All updates done.
         kwds["_all_parameters"] = parameters
 
-        # Parse keywords to organize `cf_attrs`
+        # Parse kwds to organize `cf_attrs`
         # And before converting callables to static methods
         kwds["cf_attrs"] = cls._parse_output_attrs(kwds, identifier)
+        # Parse keywords
+        if "keywords" in kwds:
+            kwds["keywords"] = cls.keywords + " " + kwds.get("keywords")
 
         # Convert function objects to static methods.
         for key in cls._funcs:

diff --git a/xclim/indicators/atmos/_precip.py b/xclim/indicators/atmos/_precip.py
@@ -71,26 +71,30 @@ class FireWeather(Indicator):
 
     src_freq = "D"
     context = "hydro"
+    keywords = "fire"
 
 
 class Precip(Daily):
     """Indicator involving daily pr series."""
 
     context = "hydro"
+    keywords = "precipitation"
 
 
 class PrecipWithIndexing(ResamplingIndicatorWithIndexing):
     """Indicator involving daily pr series and allowing indexing."""
 
     src_freq = "D"
     context = "hydro"
+    keywords = "precipitation"
 
 
 class PrTasxWithIndexing(ResamplingIndicatorWithIndexing):
     """Indicator involving pr and one of tas, tasmin or tasmax, allowing indexing."""
 
     src_freq = "D"
     context = "hydro"
+    keywords = "precipitation"
 
     def cfcheck(self, pr, tas):
         cfchecks.cfcheck_from_name("pr", pr)
@@ -108,6 +112,7 @@ class HrPrecip(Hourly):
     """Indicator involving hourly pr series."""
 
     context = "hydro"
+    keywords = "precipitation"
 
 
 rain_on_frozen_ground_days = PrTasxWithIndexing(
@@ -363,6 +368,7 @@ class HrPrecip(Hourly):
     abstract="Precipitation over a moving window, normalized such that SPI averages to 0 for the calibration data. "
     "The window unit `X` is the minimal time period defined by the resampling frequency.",
     cell_methods="",
+    keywords="precipitation",
     compute=indices.standardized_precipitation_index,
 )
 
@@ -379,6 +385,7 @@ class HrPrecip(Hourly):
     "SPEI averages to 0 for the calibration data. The window unit `X` is the minimal time period defined by the "
     "resampling frequency.",
     cell_methods="",
+    keywords="precipitation",
     compute=indices.standardized_precipitation_evapotranspiration_index,
 )
 

diff --git a/xclim/indicators/atmos/_temperature.py b/xclim/indicators/atmos/_temperature.py
@@ -93,11 +93,14 @@
 class Temp(Daily):
     """Indicators involving daily temperature."""
 
+    keywords = "temperature"
+
 
 class TempWithIndexing(ResamplingIndicatorWithIndexing):
     """Indicators involving daily temperature and adding an indexing possibility."""
 
     src_freq = "D"
+    keywords = "temperature"
 
 
 tn_days_above = TempWithIndexing(
@@ -1163,6 +1166,8 @@ class TempWithIndexing(ResamplingIndicatorWithIndexing):
 class FireSeasonBase(Indicator):
     """Special Indicator class for FireSeason that accepts any tas[min/max] and optional snd and is not resampling."""
 
+    keywords = "fire"
+
     def cfcheck(self, tas, snd=None):
         cfchecks.check_valid(tas, "standard_name", "air_temperature")
         cfchecks.cfcheck_from_name("snd", snd)

diff --git a/xclim/indicators/atmos/_wind.py b/xclim/indicators/atmos/_wind.py
@@ -19,6 +19,7 @@ class Wind(ResamplingIndicatorWithIndexing):
     """Indicator involving daily sfcWind series."""
 
     src_freq = "D"
+    keywords = "wind"
 
 
 calm_days = Wind(

diff --git a/xclim/indicators/land/_snow.py b/xclim/indicators/land/_snow.py
@@ -27,11 +27,14 @@
 class Snow(Daily):
     """Indicators dealing with snow variables."""
 
+    keywords = "snow"
+
 
 class SnowWithIndexing(ResamplingIndicatorWithIndexing):
     """Indicators dealing with snow variables, allowing indexing."""
 
     src_freq = "D"
+    keywords = "snow"
 
 
 snd_season_length = SnowWithIndexing(

diff --git a/xclim/indicators/land/_streamflow.py b/xclim/indicators/land/_streamflow.py
@@ -17,6 +17,7 @@
 class Streamflow(ResamplingIndicator):
     context = "hydro"
     src_freq = "D"
+    keywords = "streamflow hydrology"
 
     @staticmethod
     def cfcheck(q):

diff --git a/xclim/indicators/seaIce/_seaice.py b/xclim/indicators/seaIce/_seaice.py
@@ -14,6 +14,7 @@ class SiconcAreacello(Indicator):
     """Class for indicators having sea ice concentration and grid cell area inputs."""
 
     missing = "skip"
+    keywords = "seaice"
 
 
 sea_ice_extent = SiconcAreacello(