Fix documentation

doc/adv-manual/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

doc/adv-manual/conf.py

@@ -12,18 +12,16 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import os
 from openquake import engine
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+# needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -85,7 +83,6 @@
 #  Version Dropdown Config
 
 
-
 rst_epilog = """
 .. |VERSION| replace:: %s
 """ % release
@@ -96,41 +93,41 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ''
+# today = ''
 # Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#default_role = None
+# default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+# add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+# show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+# modindex_common_prefix = []
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+# keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
@@ -150,7 +147,7 @@
     "navbar_start": ["version-switcher"],
     "switcher": {
         "json_url": "../../.ddown_adv.json",
-        "version_match": "development" if it_is_master == True else '.'.join(version.split('.')[0:2])
+        "version_match": "development" if it_is_master is True else '.'.join(version.split('.')[0:2])
     },
     "icon_links": [
 
@@ -215,7 +212,7 @@
             "type": "fontawesome",  # Default is fontawesome
         }
 
-   ]
+    ]
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

doc/manual/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

doc/manual/conf.py

@@ -95,7 +95,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -171,7 +171,7 @@
     "navbar_start": ["version-switcher"],
     "switcher": {
         "json_url": "../../.ddown_man.json",
-        "version_match": "development" if it_is_master == True else '.'.join(version.split('.')[0:2])
+        "version_match": "development" if it_is_master is True else '.'.join(version.split('.')[0:2])
     },
     "icon_links": [
         {

doc/manual/hazard.rst

@@ -1099,7 +1099,7 @@ Scenario based Seismic Hazard Analysis
 In case of Scenario Based Seismic Hazard Analysis, the engine simulates a set of 
 ground motion fields (GMFs) at the target sites for the requested set of 
 intensity measure types. This set of GMFs can then be used in 
-:ref:`Scenario Damage Assessment` and :ref:`Scenario Risk Assessment`
+:ref:`sec-scenario_damage_assessment` and :ref:`sec-config_scenario_risk`
 to estimate the distribution of potential damage, economic losses, fatalities, 
 and other consequences. The scenario calculator is useful for simulating 
 both historical and hypothetical earthquakes.
@@ -2355,7 +2355,7 @@ be specifed by using the ``sites`` or ``sites_csv`` parameters,
 or the ``region`` and ``region_grid_spacing`` parameters, similar to the
 classical PSHA and event-based PSHA calculators; other options include the 
 definition of the sites through the ``site_model_file`` or the 
-exposure model (see Section :ref:`Exposure Models`).
+exposure model (see Section :ref:`sec-exposure`).
 
 The parameters unique to the scenario calculator are described below:
 
@@ -2400,15 +2400,16 @@ a ``site_model_stations.csv`` file.
       | VIGA            | LAS VIGAS    | -99.23326  | 16.7587  | seismic      | 0.355     | 0            | 0.5262        | 0                | 0.1012        | 0                |
       | VNTA            | LA VENTA     | -99.81885  | 16.91426 | seismic      | 0.2061    | 0            | 0.3415        | 0                | 0.1051        | 0                |
       | COYC            | COYUCA       | -100.08996 | 16.99778 | seismic      | 0.1676    | 0            | 0.2643        | 0                | 0.0872        | 0                |
-      | ⋮               | ⋮             | ⋮          | ⋮        | ⋮             | ⋮         | ⋮            | ⋮              | ⋮                | ⋮             | ⋮                |
+      | ⋮               | ⋮            | ⋮          | ⋮        | ⋮            | ⋮         | ⋮            | ⋮             | ⋮                | ⋮             | ⋮                |
       | UTM_14Q_041_186 | NA           | -99.7982   | 16.86687 | macroseismic | 0.6512    | 0.8059       | 0.9535        | 1.0131           | 0.4794        | 1.0822           |
       | UTM_14Q_041_185 | NA           | -99.79761  | 16.77656 | macroseismic | 0.5797    | 0.8059       | 0.8766        | 1.0131           | 0.4577        | 1.0822           |
       | UTM_14Q_040_186 | NA           | -99.89182  | 16.86655 | macroseismic | 0.477     | 0.8059       | 0.722         | 1.0131           | 0.3223        | 1.0822           |
-      | ⋮               | ⋮             | ⋮          | ⋮        | ⋮             | ⋮         | ⋮            | ⋮              | ⋮                | ⋮             | ⋮                |
+      | ⋮               | ⋮            | ⋮          | ⋮        | ⋮            | ⋮         | ⋮            | ⋮             | ⋮                | ⋮             | ⋮                |
       +-----------------+--------------+------------+----------+--------------+-----------+--------------+---------------+------------------+---------------+------------------+
 
 The following parameters are mandatory:
--  ``STATION_ID``: string; subject to the same validity checks as the ``id`` fields 
+
+-  ``STATION_ID``: string; subject to the same validity checks as the ``id`` fields
    in other input files.
 
 -  ``LONGITUDE``, ``LATITUDE``: floats; valid longitude and latitude values.
@@ -2427,6 +2428,7 @@ The following parameters are mandatory:
       using the column headers <IMT>_VALUE, <IMT>_STDDEV respectively.
 
 The following parameters are optional:
+
 -  ``STATION_NAME``: string; free form and not subject to the same constraints as the 
    `STATION_ID` field. The optional STATION_NAME field can contain information that aids 
    in identifying a particular station.

doc/manual/risk.rst

@@ -66,6 +66,8 @@ options and methodologies can be easily introduced, without affecting
 the overall calculation workflow. Each workflow is described in more
 detail in the following sections.
 
+.. _sec-scenario_damage_assessment:
+
 Scenario Damage Assessment 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 The scenario damage

doc/samples/README.md

@@ -0,0 +1,6 @@
+Files `dot_ddown_adv.json.sample` and `dot_ddown_man.json.sample` are samples of
+files `.ddown_adv.json` and `.ddown_man.json` referred by
+`oq-engine/doc/adv-manual/conf.py` and `oq-engine/doc/manual/conf.py`,
+needed by `html_theme_options['switcher']['json_url']`.
+They are meant to be found in the `oq-engine` directory.
+These files are generated automatically by .github/workflows/docs.yml

doc/samples/dot_ddown_adv.json.sample

@@ -0,0 +1 @@
+[{ "name": "3.16 (LTS)", "version": "3.16", "url": "https://docs.openquake.org/oq-engine/3.16/advanced/" }, { "name": "development", "version": "master", "url": "https://docs.openquake.org/oq-engine/master/advanced/" }]

doc/samples/dot_ddown_man.json.sample

@@ -0,0 +1 @@
+[{ "name": "3.16 (LTS)", "version": "3.16", "url": "https://docs.openquake.org/oq-engine/3.16/manual/" }, { "name": "development", "version": "master", "url": "https://docs.openquake.org/oq-engine/master/manual/" }]

doc/sphinx/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j 8 # -n -W
+SPHINXOPTS    = -j 8 -W # -n -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

doc/sphinx/openquake.hazardlib.gsim.rst

@@ -156,10 +156,10 @@ arteta_2021
     :undoc-members:
     :show-inheritance:
 
-arteta_2023_nosam
+arteta_2023
 ---------------------------------------------------
 
-.. automodule:: openquake.hazardlib.gsim.arteta_2023_nosam
+.. automodule:: openquake.hazardlib.gsim.arteta_2023
     :members:
     :undoc-members:
     :show-inheritance:

doc/sphinx/openquake.hazardlib.rst

@@ -12,8 +12,6 @@ Subpackages
     openquake.hazardlib.mfd
     openquake.hazardlib.scalerel
     openquake.hazardlib.source
-    openquake.hazardlib.source_reader
-    openquake.hazardlib.logictree
 
 
 source_reader module

openquake/hazardlib/gsim/kotha_2020.py

@@ -345,10 +345,12 @@ class KothaEtAl2020(GMPE):
     always being used if defined on input.
     In the core form of the GMPE no site term is included. This is added in the
     subclasses.
+
     :param float sigma_mu_epsilon:
         Parameter to control the source-region scaling as a number of
         standard deviations by which to multiply the source-region to source-
         region variance, max(tau_l2l, sigma_mu)
+
     :param float c3_epsilon:
         Parameter to control the residual attenuation scaling as a number
         of standard deviations by which to multiply the attenuation-region
@@ -357,13 +359,16 @@ class KothaEtAl2020(GMPE):
         attenuation as an instance of :class:
         `openquake.hazardlib.gsim.base.CoeffsTable`. If absent, the value is
         taken from the normal coefficients table.
+
     :param bool ergodic:
         Use the ergodic standard deviation (True) or non-ergodic standard
         deviation (False)
+
     :param dict dl2l:
         If specifying the source-region scaling directly, defines the
         increase or decrease of the ground motion in the form of an imt-
         dependent dictionary of delta L2L factors
+
     :param dict c3:
         If specifying the residual attenuation scaling directly, defines the
         apparent anelastic attenuation term, c3, as an imt-dependent

openquake/hazardlib/gsim/wong2022.py

@@ -19,7 +19,7 @@
 """
 Module exports :class:`WongEtAl2015`.
                :class:`WongEtAl2022Shallow`.
-               :class:`WongEtAl2022Deep.
+               :class:`WongEtAl2022Deep`.
 """
 import numpy as np
 
@@ -50,8 +50,8 @@ class WongEtAl2022Shallow(GMPE):
     Implements GMPE developed by Ivan Wong, Robert Darragh, Sarah Smith, Qimin
     Wu, Walter Silva, Tadahiro Kishida; "Ground motion models for shallow
     crustal and deep earthquakes in Hawaii and analyses of the 2018 M 6.9
-    Kalapana sequence." Earthquake Spectra 2022;; 38 (1): 579–614.  doi:
-        https://doi.org/10.1177/87552930211044521
+    Kalapana sequence." Earthquake Spectra 2022;; 38 (1): 579–614. doi:
+    https://doi.org/10.1177/87552930211044521
 
     SA are given up to 10 s.  The regressions are developed considering the
     average horizontal component of the as-recorded horizontal components

openquake/hazardlib/gsim/zhang_zhao_2005.py

@@ -139,17 +139,19 @@ def compute(self, ctx: np.recarray, imts, mean, sig, tau, phi):
     LSD           0.456   0.0552  3.204  -1.0248  -4.743    0.22
     """)
 
+
 class Zhang_Zhao2005SSlab(Zhang_Zhao2005SInter):
     """
-    Implements the GMPE of Zhang and Zhao. (2005) for Permanent ground deformation (m)
-	from lateral spread 
-    Zhang, J., & Zhao, J. X. (2005). Empirical models for estimating liquefaction-induced
-    lateral spread displacement. Soil Dynamics and Earthquake Engineering, 25(6), 439-450.
-    This model is based on Sadigh et al. (1997) and Young et al. (1997) models
+    Implements the GMPE of Zhang and Zhao. (2005) for Permanent ground
+    deformation (m) from lateral spread
+    Zhang, J., & Zhao, J. X. (2005). Empirical models for estimating
+    liquefaction-induced lateral spread displacement. Soil Dynamics and
+    Earthquake Engineering, 25(6), 439-450. This model is based on Sadigh et
+    al. (1997) and Young et al. (1997) models
     """
-    #: This GMPE is based on subduction intraslab earthquakes 
+    #: This GMPE is based on subduction intraslab earthquakes
     DEFINED_FOR_TECTONIC_REGION_TYPE = const.TRT.SUBDUCTION_INTRASLAB
-            
+
     def compute(self, ctx: np.recarray, imts, mean, sig, tau, phi):
         for m, imt in enumerate(imts):
             ctx = ctx.copy()