Restructuring of the documentation

.readthedocs.yml

@@ -22,3 +22,6 @@ python:
 
 formats:
   - pdf
+
+sphinx:
+  configuration: doc/conf.py

CONTRIBUTING.md

@@ -12,7 +12,7 @@ For orientation, these are some categories of possible contributions we can thin
 * **New Modules and Utility Functions:** Did you create a function or an entire module you find useful for your work? Maybe you are not the only one! Feel free to simply raise a pull request for functions that improve, e.g., plotting or data handling. As an entire module has to be carefully integrated into the framework, it might help if you talk to us first so we can design the module and plan the next steps. You can do that by raising an issue or starting a [discussion](https://github.com/CLIMADA-project/climada_python/discussions) on GitHub.
 
 A good place to start a personal discussion is our monthly CLIMADA developers call.
-Please contact the [lead developers](https://wcr.ethz.ch/research/climada.html) if you want to join.
+Please contact the [lead developers](https://climada.ethz.ch/team/) if you want to join.
 
 ## Why Should You Contribute?
 

climada/engine/unsequa/calc_base.py

@@ -207,7 +207,7 @@ def make_sample(self, N, sampling_method="saltelli", sampling_kwargs=None):
         sampling_method : str, optional
             The sampling method as defined in SALib. Possible choices:
             'saltelli', 'latin', 'morris', 'dgsm', 'fast_sampler', 'ff', 'finite_diff',
-             https://salib.readthedocs.io/en/latest/api.html
+            https://salib.readthedocs.io/en/latest/api.html
             The default is 'saltelli'.
         sampling_kwargs : kwargs, optional
             Optional keyword arguments passed on to the SALib sampling_method.
@@ -223,7 +223,7 @@ def make_sample(self, N, sampling_method="saltelli", sampling_kwargs=None):
         The 'ff' sampling method does not require a value for the N parameter.
         The inputed N value is hence ignored in the sampling process in the case
         of this method.
-        The 'ff' sampling method requires a number of uncerainty parameters to be
+        The 'ff' sampling method requires a number of uncertainty parameters to be
         a power of 2. The users can generate dummy variables to achieve this
         requirement. Please refer to https://salib.readthedocs.io/en/latest/api.html
         for more details.
@@ -232,7 +232,7 @@ def make_sample(self, N, sampling_method="saltelli", sampling_kwargs=None):
         See Also
         --------
         SALib.sample: sampling methods from SALib SALib.sample
-            https://salib.readthedocs.io/en/latest/api.html
+        https://salib.readthedocs.io/en/latest/api.html
 
         """
 

climada/engine/unsequa/calc_cost_benefit.py

@@ -77,7 +77,7 @@ class CalcCostBenefit(Calc):
     _metric_names : tuple(str)
         Names of the cost benefit output metrics
         ('tot_climate_risk', 'benefit', 'cost_ben_ratio',
-         'imp_meas_present', 'imp_meas_future')
+        'imp_meas_present', 'imp_meas_future')
 
     """
 

climada/engine/unsequa/calc_delta_climate.py

@@ -81,7 +81,7 @@ class CalcDeltaImpact(Calc):
     _input_var_names : tuple(str)
         Names of the required uncertainty input variables
         ('exp_initial_input_var', 'impf_initial_input_var', 'haz_initial_input_var',
-         'exp_final_input_var', 'impf_final_input_var', 'haz_final_input_var'')
+        'exp_final_input_var', 'impf_final_input_var', 'haz_final_input_var'')
     _metric_names : tuple(str)
         Names of the impact output metrics
         ('aai_agg', 'freq_curve', 'at_event', 'eai_exp')

climada/engine/unsequa/unc_output.py

@@ -84,20 +84,9 @@ class UncOutput:
     samples_df : pandas.DataFrame
         Values of the sampled uncertainty parameters. It has n_samples rows
         and one column per uncertainty parameter.
-    sampling_method : str
-        Name of the sampling method from SAlib.
-        https://salib.readthedocs.io/en/latest/api.html#
-    n_samples : int
-        Effective number of samples (number of rows of samples_df)
-    param_labels : list
-        Name of all the uncertainty parameters
     distr_dict : dict
         Comon flattened dictionary of all the distr_dict of all input variables.
         It represents the distribution of all the uncertainty parameters.
-    problem_sa : dict
-        The description of the uncertainty variables and their
-        distribution as used in SALib.
-        https://salib.readthedocs.io/en/latest/basics.html.
     """
 
     _metadata = [
@@ -192,6 +181,7 @@ def check_salib(self, sensitivity_method):
     def sampling_method(self):
         """
         Returns the sampling method used to generate self.samples_df
+        See: https://salib.readthedocs.io/en/latest/api.html#
 
         Returns
         -------

climada/hazard/base.py

@@ -225,15 +225,16 @@ def check_matrices(self):
         --------
         :py:func:`climada.util.checker.prune_csr_matrix`
 
-        Todo
-        -----
-        * Check consistency with centroids
-
         Raises
         ------
         ValueError
             If matrices are ill-formed or ill-shaped in relation to each other
         """
+
+        # Todo (Previously in docstring)
+        # -----
+        # * Check consistency with centroids
+
         u_check.prune_csr_matrix(self.intensity)
         u_check.prune_csr_matrix(self.fraction)
         if self.fraction.nnz > 0:

climada/hazard/tc_clim_change.py

@@ -71,11 +71,11 @@ def get_knutson_scaling_factor(
     in Jewson et al., (2021).
 
     Related publications:
+
     -   Knutson et al., (2020): Tropical cyclones and climate
         change assessment. Part II: Projected response to anthropogenic warming.
         Bull. Amer. Meteor. Soc., 101 (3), E303–E322,
         https://doi.org/10.1175/BAMS-D-18-0194.1.
-
     -   Jewson (2021): Conversion of the Knutson et al. (2020) Tropical Cyclone
         Climate Change Projections to Risk Model Baselines,
         https://doi.org/10.1175/JAMC-D-21-0102.1
@@ -94,15 +94,15 @@ def get_knutson_scaling_factor(
         the provided percentiles are the 10th, 25th, 50th, 75th and 90th. Please refer to the
         mentioned publications for more details.
         possible percentiles:
-            '5/10' either the 5th or 10th percentile depending on variable (see text above)
-            '25' for the 25th percentile
-            '50' for the 50th percentile
-            '75' for the 75th percentile
-            '90/95' either the 90th or 95th percentile depending on variable  (see text above)
+        - '5/10' either the 5th or 10th percentile depending on variable (see text above)
+        - '25' for the 25th percentile
+        - '50' for the 50th percentile
+        - '75' for the 75th percentile
+        - '90/95' either the 90th or 95th percentile depending on variable  (see text above)
         Default: '50'
     basin : str
         region of interest, possible choices are:
-            'NA', 'WP', 'EP', 'NI', 'SI', 'SP'
+        'NA', 'WP', 'EP', 'NI', 'SI', 'SP'
     baseline : tuple of int
         the starting and ending years that define the historical
         baseline. The historical baseline period must fall within

climada/hazard/tc_tracks.py

@@ -198,6 +198,7 @@ class TCTracks:
     ----------
     data : list(xarray.Dataset)
         List of tropical cyclone tracks. Each track contains following attributes:
+
             - time (coords)
             - lat (coords)
             - lon (coords)
@@ -216,9 +217,12 @@ class TCTracks:
             - data_provider (attrs)
             - id_no (attrs)
             - category (attrs)
+
         Computed during processing:
+
             - on_land (bool for each track position)
             - dist_since_lf (in km)
+
         Additional data variables such as "nature" (specifiying, for each track position, whether a
         system is a disturbance, tropical storm, post-transition extratropical storm etc.) might be
         included, depending on the data source and on use cases.

climada/hazard/trop_cyclone/trop_cyclone.py

@@ -408,20 +408,25 @@ def apply_climate_scenario_knu(
             are the 10th, 25th, 50th, 75th and 90th. Please refer to the mentioned publications
             for more details.
             possible percentiles:
-                '5/10' either the 5th or 10th percentile depending on variable (see text above)
-                '25' for the 25th percentile
-                '50' for the 50th percentile
-                '75' for the 75th percentile
-                '90/95' either the 90th or 95th percentile depending on variable  (see text above)
+
+                - '5/10' either the 5th or 10th percentile depending on variable (see text above)
+                - '25' for the 25th percentile
+                - '50' for the 50th percentile
+                - '75' for the 75th percentile
+                - '90/95' either the 90th or 95th percentile depending on variable  (see text above)
+
             Default: '50'
         scenario : str
             possible scenarios:
-                '2.6' for RCP 2.6
-                '4.5' for RCP 4.5
-                '6.0' for RCP 6.0
-                '8.5' for RCP 8.5
+
+                - '2.6' for RCP 2.6
+                - '4.5' for RCP 4.5
+                - '6.0' for RCP 6.0
+                - '8.5' for RCP 8.5
+
         target_year : int
             future year to be simulated, between 2000 and 2100. Default: 2050.
+
         Returns
         -------
         haz_cc : climada.hazard.TropCyclone

climada/util/api_client.py

@@ -1143,6 +1143,7 @@ def purge_cache(self, target_dir=SYSTEM_DIR, keep_testfiles=True):
         """Removes downloaded dataset files from the given directory if they have been downloaded
         with the API client, if they are beneath the given directory and if one of the following
         is the case:
+
         - there status is neither 'active' nor 'test_dataset'
         - their status is 'test_dataset' and keep_testfiles is set to False
         - their status is 'active' and they are outdated, i.e., there is a dataset with the same

climada/util/coordinates.py

@@ -2940,9 +2940,11 @@ def set_df_geometry_points(df_val, scheduler=None, crs=None):
         contains latitude and longitude columns
     scheduler : str, optional
         Scheduler type for dask map_partitions.
+
         .. deprecated:: 5.0
            This function does not use dask features anymore. The parameter has no effect
            and will be removed in a future version.
+
     crs : object (anything readable by pyproj4.CRS.from_user_input), optional
         Coordinate Reference System, if omitted or None: df_val.geometry.crs
     """

doc/_static/css/custom.css

@@ -0,0 +1,22 @@
+:root {
+
+    .navbar-brand {
+        height: 7rem;
+        max-height: 7rem;
+    }
+
+}
+
+.bd-main .bd-content .bd-article-container {
+    max-width: 100%;  /* default is 60em */
+}
+
+.bd-page-width {
+    max-width: 100rem;
+}
+
+
+html {
+    --pst-font-size-base: 16px;
+    --pst-header-height: 7rem;
+}

doc/api/index.rst

@@ -0,0 +1,11 @@
+==============
+API Reference
+==============
+
+Could be nice to have an API section homepage
+
+.. toctree::
+   :caption: API Reference
+   :hidden:
+
+   Modules <climada/climada>

doc/conf.py

@@ -40,6 +40,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.ifconfig",
+    "sphinx_design",
     "myst_nb",
     "sphinx_markdown_tables",
     "readthedocs_ext.readthedocs",
@@ -123,12 +124,27 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = "sphinx_book_theme"
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "header_links_before_dropdown": 8,
+    "navbar_align": "left",
+    # "icon_links": [
+    #     {
+    #         # Label for this link
+    #         "name": "GitHub",
+    #         # URL where the link will redirect
+    #         "url": "https://github.com/CLIMADA-project",  # required
+    #         # Icon class (if "type": "fontawesome"), or path to local image (if "type": "local")
+    #         "icon": "fa-brands fa-square-github",
+    #         # The type of image to be used (see below for details)
+    #         "type": "fontawesome",
+    #     }
+    # ],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -154,6 +170,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_css_files = [
+    "css/custom.css",
+]
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'