Use genno.compat.sphinx.rewrite_refs

- Add configuration.
- Address ~270 of ~450 nitpick warnings in Sphinx build.
- Remove custom ReST aliases.
- Remove some nitpick_ignore_regex entries.

doc/api/disutility.rst

@@ -14,15 +14,15 @@ Method & usage
 Use this code by calling :func:`add`, which takes arguments that describe the concrete usage:
 
 Consumer groups
-   This is a list of |Code| objects describing the consumer groups.
+   This is a list of :class:`.Code` objects describing the consumer groups.
    The list must be 1-dimensional, but can be composed (as in :mod:`message_data.model.transport`) from multiple dimensions.
 
 Technologies
-   This is a list of |Code| objects describing the technologies for which the consumers in the different groups experience disutility.
+   This is a list of :class:`.Code` objects describing the technologies for which the consumers in the different groups experience disutility.
    Each object must be have 'input' and 'output' annotations (:attr:`~.Code.annotations`); each of these is a :class:`dict` with the keys 'commodity', 'input', and 'unit', describing the source or sink for the technology.
 
 Template
-   This is also a |Code| object, similar to those in ``technologies``; see below.
+   This is also a :class:`.Code` object, similar to those in ``technologies``; see below.
 
 The code creates a source technology for the “disutility” commodity.
 The code does *not* perform the following step(s) needed to completely parametrize the formulation:

doc/api/report/index.rst

@@ -37,7 +37,7 @@ In short, for instance:
 
 The basic **design pattern** of :mod:`message_ix_models.report` is:
 
-- :func:`~.report.prepare_reporter` populates a new :class:`~.message_ix.Reporter` for a given |Scenario| with many keys to report all quantities of interest in a MESSAGEix-GLOBIOM–family model.
+- :func:`~.report.prepare_reporter` populates a new :class:`~.message_ix.Reporter` for a given :class:`.Scenario` with many keys to report all quantities of interest in a MESSAGEix-GLOBIOM–family model.
 - This function relies on *callbacks* defined in multiple submodules to add keys and tasks for general or tailored reporting calculations and actions.
   Additional modules **should** define callback functions and register them with :func:`~report.register` when they are to be used.
   For example:
@@ -145,7 +145,7 @@ Operators
 
      - :mod:`message_ix.report.operator`
      - :mod:`ixmp.report.operator`
-     - :mod:`genno.computations`
+     - :mod:`genno.operator`
 
    - Other submodules:
 

doc/cli.rst

@@ -172,7 +172,7 @@ Further information about the top-level options:
    These options direct it to work with a different Platform.
 
 :program:`--model MODEL --scenario SCENARIO` or :program:`--url`
-    Many commands use an *existing* |Scenario| as a starting point, and begin by cloning that Scenario to a new (model name, scenario name).
+    Many commands use an *existing* :class:`.Scenario` as a starting point, and begin by cloning that Scenario to a new (model name, scenario name).
     For any such command, these top-level options define the starting point/initial Scenario to clone/‘baseline’.
 
     In contrast, see :program:`--output-model`, below.

doc/conf.py

@@ -22,14 +22,16 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions coming
 # with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    # "ixmp.util.sphinx_linkcode_github",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    # Others
+    "genno.compat.sphinx.rewrite_refs",
+    # "ixmp.util.sphinx_linkcode_github",
     "sphinxcontrib.bibtex",
 ]
 
@@ -43,12 +45,8 @@
 
 nitpicky = True
 nitpick_ignore_regex = {
-    # These occur because there is no .. py:module:: directive for the *top-level*
-    # module or package in the respective documentation and inventories.
-    # TODO Remove once the respective docs are fixed
-    ("py:mod", "ixmp"),
-    ("py:mod", "message_ix"),
-    ("py:mod", "message_data"),
+    # Legacy reporting docstrings are not formatted
+    ("py:.*", r"boolean \(default|str \(default|None\)|False\)"),
     # iam-units has no Sphinx docs
     ("py:.*", "iam_units.*"),
     # These are a consequence of autosummary-class.rst
@@ -59,12 +57,6 @@
 .. role:: py(code)
    :language: python
 
-.. |Annotation| replace:: :class:`~sdmx.model.common.Annotation`
-.. |Code| replace:: :class:`~sdmx.model.common.Code`
-.. |Codelist| replace:: :class:`~sdmx.model.common.Codelist`
-.. |Platform| replace:: :class:`~ixmp.Platform`
-.. |Scenario| replace:: :class:`~message_ix.Scenario`
-
 .. |n| replace:: :math:`n`
 .. |y| replace:: :math:`y`
 .. |y0| replace:: :math:`y_0`
@@ -101,6 +93,34 @@ def setup(app: "sphinx.application.Sphinx") -> None:
 # builtin themes.
 html_theme = "sphinx_rtd_theme"
 
+# -- Options for genno.compat.sphinx.rewrite_refs --------------------------------------
+
+# When base classes in upstream (genno, ixmp) packages are inherited in message_ix,
+# Sphinx will not properly resolve relative references within docstrings of methods of
+# the former. Some of these aliases are to allow Sphinx to locate the correct targets.
+reference_aliases = {
+    # genno
+    "Computer": "genno.Computer",
+    "KeyLike": ":data:`genno.core.key.KeyLike`",
+    r"(genno\.|)Key(?=Seq|[^\w]|$)": "genno.core.key.Key",
+    r"(genno\.|)Quantity": "genno.core.attrseries.AttrSeries",
+    # ixmp
+    "Platform": "ixmp.Platform",
+    "TimeSeries": "ixmp.TimeSeries",
+    # message_ix
+    r"Scenario(?=[^\w]|$)": "message_ix.Scenario",
+    "Reporter": "message_ix.report.Reporter",
+    "make_df": "message_ix.util.make_df",
+    # sdmx
+    "Code": "sdmx.model.common.Code",
+    #
+    # Many projects (including Sphinx itself!) do not have a py:module target in for the
+    # top-level module in objects.inv. Resolve these using :doc:`index` or similar for
+    # each project.
+    "pint$": ":std:doc:`pint <pint:index>`",
+    "plotnine$": ":class:`plotnine.ggplot`",
+}
+
 # -- Options for sphinx.ext.autosummary ------------------------------------------------
 
 autosummary_generate = True
@@ -159,7 +179,8 @@ def local_inv(name: str, *parts: str) -> Optional[str]:
 
 napoleon_preprocess_types = True
 napoleon_type_aliases = {
-    "Code": ":class:`~sdmx.model.common.Code`",
+    "iterable": ":class:`~collections.abc.Iterable`",
+    "sequence": ":class:`~collections.abc.Sequence`",
     "Path": ":class:`~pathlib.Path`",
     "PathLike": ":class:`os.PathLike`",
 }

doc/data.rst

@@ -201,7 +201,7 @@ Fetch directly from a remote source
 This corresponds to section (1) above.
 Preferably, do this via :mod:`message_ix_models.util.pooch`:
 
-- Extend :mod:`.pooch.SOURCE` to store the Internet location, file name(s), and hash(es) of the file(s).
+- Extend :data:`.pooch.SOURCE` to store the Internet location, file name(s), and hash(es) of the file(s).
 - Call :func:`.pooch.fetch` to retrieve the file and cache it locally.
 - Write code in :mod:`message_ix_models` that processes the data into a common format, for instance by subclassing :class:`.ExoDataSource`.
 

doc/whatsnew.rst

@@ -51,7 +51,7 @@ Update code that imports from the following modules:
 
 Code that imports from the old locations will continue to work, but will raise :class:`DeprecationWarning`.
 
-Data for :doc:`water` is no longer included in the PyPI distributions for :mod:`message_ix_models`.
+Data for :doc:`water/index` is no longer included in the PyPI distributions for :mod:`message_ix_models`.
 This reduces the package size from >20 MB to <5 MB.
 To automatically download and unpack these data into a local directory, use :program:`mix-models fetch MESSAGEix-Nexus`.
 
@@ -89,7 +89,7 @@ v2023.10.16
 - New providers for exogenous data from the :class:`.SSPOriginal` and :class:`.SSPUpdate` (:pull:`125`) sources.
 - Improved :class:`.ScenarioInfo` (:pull:`125`):
 
-  - New attributes :attr:`~.ScenarioInfo.model`, :attr:`~.ScenarioInfo.scenario`, :attr:`~.ScenarioInfo.version`, and (settable) :attr:`~.ScenarioInfo.url`; class method :meth:`~.ScenarioInfo.from_url` to allow storing |Scenario| identifiers on ScenarioInfo objects.
+  - New attributes :attr:`~.ScenarioInfo.model`, :attr:`~.ScenarioInfo.scenario`, :attr:`~.ScenarioInfo.version`, and (settable) :attr:`~.ScenarioInfo.url`; class method :meth:`~.ScenarioInfo.from_url` to allow storing :class:`.Scenario` identifiers on ScenarioInfo objects.
   - New property :attr:`~.ScenarioInfo.path`, giving a valid path name for scenario-specific file I/O.
 
 - Improvements to :mod:`~message_ix_models.report` (:pull:`125`):
@@ -198,7 +198,7 @@ v2023.5.13
 2022.8.17
 =========
 
-- Add :func:`.nodes_ex_world` and use this in :func:`.disutility.data_conversion` instead of expected a "World" node ID to be the first element in :attr:`.ScenarioInfo.N` (:pull:`78`).
+- Add :func:`~.util.node.nodes_ex_world` and use this in :func:`.disutility.data_conversion` instead of expected a "World" node ID to be the first element in :attr:`.ScenarioInfo.N` (:pull:`78`).
 - Add example files and documentation for :doc:`pkg-data/iiasa-se` (:pull:`78`).
 - Expand :file:`~` (i.e. ``$HOME``) in the ``"message local data"`` :ref:`configuration setting <local-data>` (:pull:`78`).
 
@@ -246,7 +246,7 @@ v2023.5.13
 - New :class:`.Spec` class for easier handling of specifications of model (or model variant) structure (:pull:`39`)
 - New utility function :func:`.util.local_data_path` (:pull:`39`).
 - :func:`.repr` of :class:`.Context` no longer prints a (potentially very long) list of all keys and settings (:pull:`39`).
-- :func:`.as_codes` accepts a :class:`.dict` with |Code| values (:pull:`39`).
+- :func:`.as_codes` accepts a :class:`.dict` with :class:`.Code` values (:pull:`39`).
 
 Earlier releases
 ================
@@ -265,15 +265,15 @@ Earlier releases
 2021.7.22
 ---------
 
-- Migrate utilities :func:`cached`, :func:`.check_support`, :func:`.convert_units`, :func:`.maybe_query`, :func:`.series_of_pint_quantity` (:pull:`27`)
+- Migrate utilities :func:`.cached`, :func:`.check_support`, :func:`.convert_units`, :func:`.maybe_query`, :func:`.series_of_pint_quantity` (:pull:`27`)
 - Add :data:`.testing.NIE`.
 - Add the ``--jvmargs`` option to :command:`pytest` (see :func:`.pytest_addoption`).
-- Remove :meth:`.Context.get_config_file`, :meth:`.get_path`, :meth:`.load_config`, and :meth:`.units`, all deprecated since 2021-02-28.
+- Remove :py:`.Context.get_config_file()`, :py:`.get_path()`, :py:`.load_config()`, and :py:`.units`, all deprecated since 2021-02-28.
 
 2021.7.6
 --------
 
-- Add :func:`identify_nodes`, a function for identifying a :doc:`pkg-data/node` based on a |Scenario| (:pull:`24`).
+- Add :func:`.identify_nodes`, a function for identifying a :doc:`pkg-data/node` based on a :class:`.Scenario` (:pull:`24`).
 - Add :obj:`.adapt_R11_R14`, a function for adapting data from the :ref:`R11` to the :ref:`R14` node lists (:pull:`24`).
 - Add :func:`.export_test_data` and :command:`mix-models export-test-data` command (:pull:`16`).
   See :ref:`export-test-data`.
@@ -300,8 +300,8 @@ Earlier releases
 2021.3.3
 --------
 
-- Migrate :mod:`.util.click`, :mod:`.util.logging`; expand documentation (:pull:`8`:).
-- :meth:`.Context.clone_to_dest` method replaces :func:`clone_to_dest` function.
+- Migrate :mod:`.util.click`, :mod:`.util.logging <.util._logging>`; expand documentation (:pull:`8`:).
+- :meth:`.Context.clone_to_dest` method replaces :py:`clone_to_dest()` function.
 - Build PDF documentation on ReadTheDocs.
 - Allow CLI commands from both :mod:`message_ix_models` and :mod:`message_data` via :program:`mix-models`.
 - Migrate :program:`mix-models techs` CLI command.

message_ix_models/model/bare.py

@@ -35,9 +35,9 @@ def create_res(context, quiet=True):
 
     Parameters
     ----------
-    context : Context
-        :attr:`.Context.scenario_info` determines the model name and scenario name of
-        the created Scenario. If not provided, the defaults are:
+    context : .Context
+        :attr:`.model.Config.scenario_info` determines the model name and scenario name
+        of the created Scenario. If not provided, the defaults are:
 
         - Model name generated by :func:`name`.
         - Scenario name "baseline".

message_ix_models/model/disutility.py

@@ -48,11 +48,11 @@ def get_spec(
 
     Parameters
     ----------
-    groups : list of |Code|
+    groups : list of .Code
         Identities of the consumer groups with distinct disutilities.
-    technologies : list of |Code|
+    technologies : list of .Code
         The technologies to which the disutilities are applied.
-    template : |Code|
+    template : .Code
 
     """
     s = Spec()

message_ix_models/model/emissions.py

@@ -31,7 +31,7 @@ def get_emission_factors(units: Optional[str] = None) -> Quantity:
 
     Parameters
     ----------
-    unit : str, *optional*
+    unit : str, optional
         Expression for units of the returned quantity. Tested values include:
 
         - “tC / TJ”, source units (default),

message_ix_models/model/macro.py

@@ -44,8 +44,8 @@ def generate(
       node list indicated by :attr:`.model.Config.regions`.
     - "year": All periods from the period *before* the first model year.
     - "commodity": The elements of `commodities`.
-    - "sector": If each entry of `commodities` is a |Code| and has an annotation with
-      id="macro-sector", the value of that annotation. Otherwise, the same as
+    - "sector": If each entry of `commodities` is a :class:`.Code` and has an annotation
+      with id="macro-sector", the value of that annotation. Otherwise, the same as
       `commodity`.
 
     `value` supplies the parameter value, which is the same for all observations.
@@ -57,7 +57,7 @@ def generate(
         MACRO parameter for which to generate data.
     context
         Used with :func:`.bare.get_spec`.
-    commodities : list of str or |Code|
+    commodities : list of str or .Code
         Commodities to include in the MESSAGE-MACRO linkage.
     value : float
         Parameter value.

message_ix_models/model/structure.py

@@ -94,7 +94,7 @@ def get_codes(name: str) -> List[Code]:
 
 @lru_cache()
 def get_codelist(name: str) -> Codelist:
-    """Return a |Codelist| for the dimension/set `name` in MESSAGE-GLOBIOM scenarios."""
+    """Return a :class:`.Codelist` for `name` in MESSAGEix-GLOBIOM scenarios."""
     cl = Codelist(id=name.replace("/", "_").upper())
     cl.extend(get_codes(name))
     return cl

message_ix_models/report/__init__.py

@@ -194,7 +194,7 @@ def log_before(context, rep, key) -> None:
 
 
 def report(context: Context, *args, **kwargs):
-    """Report (post-process) solution data in a |Scenario| and store time series data.
+    """Report (post-process) solution data in a :class:`.Scenario`.
 
     This function provides a single, common interface to call both the :mod:`genno`
     -based (:mod:`message_ix_models.report`) and ‘legacy’ (
@@ -299,14 +299,14 @@ def prepare_reporter(
     scenario: Optional[Scenario] = None,
     reporter: Optional[Reporter] = None,
 ) -> Tuple[Reporter, Key]:
-    """Return a :class:`message_ix.Reporter` and `key` prepared to report a |Scenario|.
+    """Return a :class:`.Reporter` and `key` prepared to report a :class:`.Scenario`.
 
     Parameters
     ----------
-    context : Context
+    context : .Context
         The code responds to :py:`context.report`, which is an instance of
         :class:`.report.Config`.
-    scenario : Scenario, optional
+    scenario : .Scenario, optional
         Scenario to report. If not given, :meth:`.Context.get_scenario` is used to
         retrieve a Scenario.
     reporter : .Reporter, optional

message_ix_models/report/compat.py

@@ -102,14 +102,14 @@ def func(
         ----------
         technologies :
             List of technology IDs to include.
-        name : str, *optional*
+        name : str, optional
             If given, the name of the resulting key. Default: a name like "_123"
             generated with :func:`anon`.
-        filters : dict, *optional*
+        filters : dict, optional
             Additional filters for selecting data from "{base_name}:*". Keys are short
             dimension names (for instance, "c" for "commodity"); values are lists of
             IDs.
-        unit_key : str, *optional*
+        unit_key : str, optional
             Key for units to apply to the result. Must appear in :attr:`.Config.units`.
         """
         base = single_key(c.full_key(base_name))
@@ -153,9 +153,9 @@ def eff(
 
     Parameters
     ----------
-    filters_in : dict, *optional*
+    filters_in : dict, optional
         Passed as the `filters` parameter to :func:`inp`.
-    filters_out : dict, *optional*
+    filters_out : dict, optional
         Passed as the `filters` parameter to :func:`out`.
     """
     # TODO Check whether append / drop "t" is necessary

message_ix_models/report/config.py

@@ -72,7 +72,7 @@ def use_file(self, file_path: Union[str, Path, None]) -> None:
 
         Parameters
         ----------
-        file_path : PathLike, *optional*
+        file_path : PathLike, optional
             This may be:
 
             1. The complete path to any existing file.

message_ix_models/report/operator.py

@@ -219,12 +219,12 @@ def remove_ts(
 def from_url(url: str, cls=ixmp.TimeSeries) -> ixmp.TimeSeries:
     """Return a :class:`ixmp.TimeSeries` or subclass instance, given its `url`.
 
-    .. todo:: Move upstream, to :mod:`ixmp.reporting`.
+    .. todo:: Move upstream, to :mod:`ixmp.report`.
 
     Parameters
     ----------
-    cls : type, *optional*
-        Subclass to instantiate and return; for instance, |Scenario|.
+    cls : type, optional
+        Subclass to instantiate and return; for instance, :class:`.Scenario`.
     """
     ts, mp = cls.from_url(url)
     assert ts is not None

message_ix_models/report/plot.py

@@ -47,8 +47,8 @@ class MyPlot(Plot):
 
        c.add("plot myplot", MyPlot, "scenario")
 
-    …that is, giving "scenario" or another key that points to a |Scenario| object with
-    stored time series data. See the examples in this file.
+    …that is, giving "scenario" or another key that points to a :class:`.Scenario`
+    object with stored time series data. See the examples in this file.
     """
 
     #: 'Static' geoms: list of plotnine objects that are not dynamic.
@@ -71,7 +71,7 @@ class MyPlot(Plot):
     inputs: Sequence[str] = []
 
     #: List of regular expressions corresponding to :attr:`inputs`. These are passed as
-    #: the `expr` argument to :func:`filter_ts` to filter the entire set of time series
+    #: the `expr` argument to :func:`.filter_ts` to filter the entire set of time series
     #: data.
     inputs_regex: List[re.Pattern] = []
 

message_ix_models/report/sim.py

@@ -148,10 +148,10 @@ def add_simulated_solution(
 
     Parameters
     ----------
-    data : dict or pandas.DataFrame, *optional*
+    data : dict or pandas.DataFrame, optional
         If given, a mapping from MESSAGE item (set, parameter, or variable) names to
         inputs that are passed to :func:`simulate_qty`.
-    path : Path, *optional*
+    path : Path, optional
         If given, a path to a directory containing one or more files with names like
         :file:`ACT.csv.gz`. These files are taken as containing "simulated" model
         solution data for the MESSAGE variable with the same name. See