Merge pull request #699 from Ouranosinc/split-custom-and-ind-doc

Documentation updates
Ouranosinc · Apr 30, 2021 · e637448 · e637448
2 parents 1cd5c88 + 1f2d5c4
commit e637448
Show file tree

Hide file tree

Showing 15 changed files with 509 additions and 543 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -68,7 +68,12 @@ Other utilities
    :undoc-members:
    :show-inheritance:
 
-.. automodule:: xclim.core.checks
+.. automodule:: xclim.core.cfchecks
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: xclim.core.datachecks
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/autodoc_indicator.py b/docs/autodoc_indicator.py
@@ -4,7 +4,7 @@
 
 Based on https://github.com/powerline/powerline/blob/83d855d3d73498c47553afeba212415990d95c54/docs/source/powerline_autodoc.py
 """
-from sphinx.domains.python import PyFunction
+from sphinx.domains.python import PyFunction, PyXRefRole
 from sphinx.ext import autodoc
 
 from xclim.core.indicator import Indicator
@@ -25,3 +25,4 @@ class IndicatorDirective(PyFunction):
 def setup(app):
     app.add_autodocumenter(IndicatorDocumenter)
     app.add_directive_to_domain("py", "indicator", IndicatorDirective)
+    app.add_role_to_domain("py", "indicator", PyXRefRole())
diff --git a/docs/indicators_api.rst b/docs/indicators_api.rst
@@ -13,9 +13,9 @@
    :undoc-members:
    :imported-members:
 
-==================
-Virtual submodules
-==================
+============================
+Virtual indicator submodules
+============================
 
 .. automodule:: xclim.indicators.cf
    :members:

diff --git a/docs/internationalization.rst b/docs/internationalization.rst
@@ -1,7 +1,3 @@
 .. automodule:: xclim.core.locales
    :members:
    :show-inheritance:
-
-.. automodule:: xclim.locales
-   :members:
-   :show-inheritance:
diff --git a/docs/itable.rst b/docs/itable.rst
diff --git a/docs/notebooks/customize.ipynb b/docs/notebooks/customize.ipynb
diff --git a/docs/notebooks/example.ipynb b/docs/notebooks/example.ipynb
@@ -909,7 +909,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.6"
+   "version": "3.8.8"
   }
  },
  "nbformat": 4,

diff --git a/docs/notebooks/extendxclim.ipynb b/docs/notebooks/extendxclim.ipynb
diff --git a/docs/notebooks/index.rst b/docs/notebooks/index.rst
@@ -10,6 +10,6 @@ Examples
    ensembles-advanced
    frequency_analysis
    customize
-   mappings
+   extendxclim
    sdba
    sdba-advanced
diff --git a/docs/notebooks/mappings.ipynb b/docs/notebooks/mappings.ipynb
diff --git a/docs/notebooks/usage.ipynb b/docs/notebooks/usage.ipynb
@@ -272,7 +272,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.6"
+   "version": "3.8.8"
   }
  },
  "nbformat": 4,

diff --git a/xclim/core/calendar.py b/xclim/core/calendar.py
@@ -131,7 +131,7 @@ def convert_calendar(
       If `target` is given as an array, the output is reindexed to it, with fill value `missing`.
       If `target` was a string and `missing` was None (default), invalid dates in the new calendar are dropped, but missing dates are not inserted.
       If `target` was a string and `missing` was given, then start, end and frequency of the new time axis are inferred and
-         the output is reindexed to that a new array.
+      the output is reindexed to that a new array.
 
     Notes
     -----

diff --git a/xclim/core/indicator.py b/xclim/core/indicator.py
@@ -8,7 +8,7 @@
 the class runs data and metadata health checks. After computations, the class masks values that should be considered
 missing and adds metadata attributes to the output object.
 
-There are many ways to construct indicators. A good place to start is `this notebook <notebooks/customize.ipynb#Defining-new-indicators>`_.
+There are many ways to construct indicators. A good place to start is `this notebook <notebooks/extendxclim.ipynb#Defining-new-indicators>`_.
 
 Dictionary and YAML parser
 --------------------------
@@ -22,6 +22,8 @@
 
 Indicator-defining yaml files are structured in the following way:
 
+.. code-block:: yaml
+
     module: <module name>  # Defaults to the file name
     realm: <realm>  # If given here, applies to all indicators that do no give it.
     base: <base indicator class>  # Defaults to "Daily"
@@ -74,8 +76,8 @@
 In the following, the section under `<identifier>` is refered to as `data`. When creating indicators from
 a dictionary, with :py:meth:`Indicator.from_dict`, the input dict must follow the structure of `data`.
 
-Parameters
-~~~~~~~~~~
+Indicator parameters
+~~~~~~~~~~~~~~~~~~~~
 `clix-meta` defines three kinds of parameters:
 
     - "quantity", a quantity with a magnitude and some units, (equivalent to xclim.core.utils.InputKind.QUANTITY_STR)

diff --git a/xclim/indices/_conversion.py b/xclim/indices/_conversion.py
@@ -271,7 +271,7 @@ def relative_humidity(
     method: str = "sonntag90",
     invalid_values: str = "clip",
 ) -> xr.DataArray:
-    """Relative humidity.
+    r"""Relative humidity.
 
     Compute relative humidity from temperature and either dewpoint temperature or specific humidity and pressure through
     the saturation vapor pressure.

diff --git a/xclim/indices/fwi.py b/xclim/indices/fwi.py
@@ -39,20 +39,20 @@
 ----------
 Codes:
 
-[CFS2015] Updated source code for calculating fire danger indexes in the Canadian Forest Fire Weather Index System, Y. Wang, K.R. Anderson, and R.M. Suddaby, INFORMATION REPORT NOR-X-424, 2015.
-[cffdrs] Cantin, A., Wang, X., Parisien M-A., Wotton, M., Anderson, K., Moore, B., Schiks, T., Flannigan, M., Canadian Forest Fire Danger Rating System, R package, CRAN, https://cran.r-project.org/package=cffdrs
+.. [CFS2015] Updated source code for calculating fire danger indexes in the Canadian Forest Fire Weather Index System, Y. Wang, K.R. Anderson, and R.M. Suddaby, INFORMATION REPORT NOR-X-424, 2015.
+.. [cffdrs] Cantin, A., Wang, X., Parisien M-A., Wotton, M., Anderson, K., Moore, B., Schiks, T., Flannigan, M., Canadian Forest Fire Danger Rating System, R package, CRAN, https://cran.r-project.org/package=cffdrs
 
 https://cwfis.cfs.nrcan.gc.ca/background/dsm/fwi
 
 Fire season determination methods:
 
-[WF93] Wotton, B.M. and Flannigan, M.D. (1993). Length of the fire season in a changing climate. ForestryChronicle, 69, 187-192.
-[LA08] Lawson B.D. and Armitage O.B. 2008. Weather Guide for the Canadian Forest Fire Danger RatingSystem. Natural Resources Canada, Canadian Forest Service, Northern Forestry Centre, Edmonton,Alberta. 84 p.http://cfs.nrcan.gc.ca/pubwarehouse/pdfs/29152.pdf
+.. [WF93] Wotton, B.M. and Flannigan, M.D. (1993). Length of the fire season in a changing climate. ForestryChronicle, 69, 187-192.
+.. [LA08] Lawson B.D. and Armitage O.B. 2008. Weather Guide for the Canadian Forest Fire Danger RatingSystem. Natural Resources Canada, Canadian Forest Service, Northern Forestry Centre, Edmonton,Alberta. 84 p.http://cfs.nrcan.gc.ca/pubwarehouse/pdfs/29152.pdf
 
 Drought Code overwintering:
 
-[VW85] Van Wagner, C.E. 1985. Drought, timelag and fire danger rating. Pages 178-185 in L.R. Donoghueand R.E. Martin, eds.  Proc.  8th Conf.  Fire For.  Meteorol., 29 Apr.-3 May 1985, Detroit, MI. Soc.Am. For., Bethesda, MD.http://cfs.nrcan.gc.ca/pubwarehouse/pdfs/23550.pd
-[ME19] McElhinny, M., Beckers, J. F., Hanes, C., Flannigan, M., and Jain, P.: A high-resolution reanalysis of global fire weather from 1979 to 2018 – overwintering the Drought Code, Earth Syst. Sci. Data, 12, 1823–1833, https://doi.org/10.5194/essd-12-1823-2020, 2020.
+.. [VW85] Van Wagner, C.E. 1985. Drought, timelag and fire danger rating. Pages 178-185 in L.R. Donoghueand R.E. Martin, eds.  Proc.  8th Conf.  Fire For.  Meteorol., 29 Apr.-3 May 1985, Detroit, MI. Soc.Am. For., Bethesda, MD.http://cfs.nrcan.gc.ca/pubwarehouse/pdfs/23550.pd
+.. [ME19] McElhinny, M., Beckers, J. F., Hanes, C., Flannigan, M., and Jain, P.: A high-resolution reanalysis of global fire weather from 1979 to 2018 – overwintering the Drought Code, Earth Syst. Sci. Data, 12, 1823–1833, https://doi.org/10.5194/essd-12-1823-2020, 2020.
 """
 # This file is structured in the following way:
 # Section 1: individual codes, numba-accelerated and vectorized functions.
@@ -682,12 +682,11 @@ def fire_weather_ufunc(
     """Fire Weather Indexes computation using xarray's apply_ufunc.
 
     No unit handling. Meant to be used by power users only. Please prefer using the
-    :py:indicator:`drought_code` and :py:indicator:`fire_weather_indexes` indicators or
+    :py:indicator:`DC` and :py:indicator:`FWI` indicators or
     the :py:func:`drought_code` and :py:func:`fire_weather_indexes` indices defined in the same
     submodule.
 
     Dask arrays must have only one chunk along the "time" dimension.
-
     User can control which indexes are computed with the `indexes` argument.
 
     Parameters