Merge pull request #8812 from gem/fix-doc

Fix documentation

doc/adv-manual/Makefile

@@ -2,7 +2,10 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+# NOTE: -W treats also warnings as errors and produces an exit code != 0 in presence
+#       of any warning or error. A bug in sphinx causes the build to produce an
+#       exit code == 0 if -W is not set, regardless from the presence of any error.
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

doc/adv-manual/conf.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
-# OpenQuake for Advanced Users documentation build configuration file, created by
-# sphinx-quickstart on Fri Mar  2 07:29:39 2018.
+# OpenQuake for Advanced Users documentation build configuration file, created
+# by sphinx-quickstart on Fri Mar  2 07:29:39 2018.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -12,18 +12,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import shutil
 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 +85,6 @@
 #  Version Dropdown Config
 
 
-
 rst_epilog = """
 .. |VERSION| replace:: %s
 """ % release
@@ -96,41 +95,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
@@ -143,14 +142,19 @@
 # html_theme = 'alabaster'
 html_theme = 'pydata_sphinx_theme'
 
+json_url_path = "../../.ddown_adv.json"
+if not os.path.exists(json_url_path):
+    shutil.copyfile("../samples/dot_ddown_adv.json.sample",
+                    json_url_path)
+
 # 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 = {
     "navbar_start": ["version-switcher"],
     "switcher": {
-        "json_url": "../../.ddown_adv.json",
-        "version_match": "development" if it_is_master == True else '.'.join(version.split('.')[0:2])
+        "json_url": json_url_path,
+        "version_match": "development" if it_is_master is True else '.'.join(version.split('.')[0:2])
     },
     "icon_links": [
 
@@ -215,7 +219,7 @@
             "type": "fontawesome",  # Default is fontawesome
         }
 
-   ]
+    ]
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

doc/manual/Makefile

@@ -2,7 +2,10 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+# NOTE: -W treats also warnings as errors and produces an exit code != 0 in presence
+#       of any warning or error. A bug in sphinx causes the build to produce an
+#       exit code == 0 if -W is not set, regardless from the presence of any error.
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

doc/manual/conf.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
-# OpenQuake for Advanced Users documentation build configuration file, created by
-# sphinx-quickstart on Fri Mar  2 07:29:39 2018.
+# OpenQuake for Advanced Users documentation build configuration file, created
+# by sphinx-quickstart on Fri Mar  2 07:29:39 2018.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -12,18 +12,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import shutil
 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
@@ -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:
@@ -105,7 +105,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build','old']
+exclude_patterns = ['_build', 'old']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -167,11 +167,16 @@
 #html_logo = '_static/oq_logo.png'
 html_logo = None
 
+json_url_path = "../../.ddown_man.json"
+if not os.path.exists(json_url_path):
+    shutil.copyfile("../samples/dot_ddown_man.json.sample",
+                    json_url_path)
+
 html_theme_options = {
     "navbar_start": ["version-switcher"],
     "switcher": {
-        "json_url": "../../.ddown_man.json",
-        "version_match": "development" if it_is_master == True else '.'.join(version.split('.')[0:2])
+        "json_url": json_url_path,
+        "version_match": "development" if it_is_master is True else '.'.join(version.split('.')[0:2])
     },
     "icon_links": [
         {
@@ -235,7 +240,7 @@
             "type": "fontawesome",  # Default is fontawesome
         }
 
-   ]
+    ]
 }
 
 # The name of an image file (relative to this directory) to use as a favicon of
@@ -316,17 +321,20 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-'pointsize': '12pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    'pointsize': '12pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
 
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
+    # Latex figure (float) alignment
+    # 'figure_align': 'htbp',
+    'utf8extra': r"""
+\DeclareUnicodeCharacter{22EE}{\ensuremath{\vdots}}
+""",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

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,10 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j 8 # -n -W
+# NOTE: -W treats also warnings as errors and produces an exit code != 0 in presence
+#       of any warning or error. A bug in sphinx causes the build to produce an
+#       exit code == 0 if -W is not set, regardless from the presence of any error.
+SPHINXOPTS    = -j 8 -W --keep-going # -n
 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,6 +345,7 @@ 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-

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