diff --git a/CHANGES.rst b/CHANGES.rst index 141113c06..b530cf4b5 100644 --- 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 index cbaacbac5..d657a63f4 100644 --- a/docs/_static/indsearch.js +++ b/docs/_static/indsearch.js @@ -67,7 +67,7 @@ function indTemplate(ind) {
${ind.title} - + ${ind.module}.${ind.name}
diff --git a/docs/api.rst b/docs/api.rst index 8e91a0600..65631ee85 100644 --- 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 new file mode 100644 index 000000000..d24dfd2e2 --- /dev/null +++ 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 index 7388c4859..958240d49 100644 --- 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 index 4aeb7bb2a..5b323423e 100644 --- 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 index 988a09476..431634e84 100644 --- a/xclim/indicators/atmos/_precip.py +++ b/xclim/indicators/atmos/_precip.py @@ -71,12 +71,14 @@ 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): @@ -84,6 +86,7 @@ class PrecipWithIndexing(ResamplingIndicatorWithIndexing): src_freq = "D" context = "hydro" + keywords = "precipitation" class PrTasxWithIndexing(ResamplingIndicatorWithIndexing): @@ -91,6 +94,7 @@ class PrTasxWithIndexing(ResamplingIndicatorWithIndexing): 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 index 0182b3316..b1828cbc9 100644 --- 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 index 9525c63e1..3e63036ad 100644 --- 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 index 458109a37..f2294d1ab 100644 --- 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 index 3ea312d68..0a6d11dfb 100644 --- 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 index 61156d14f..ec9f52b4e 100644 --- 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(