Use semantic line breaks in doc/api/report/index

Author: khaeru

doc/api/report/index.rst

@@ -31,32 +31,59 @@ Introduction
 See :doc:`the discussion in the MESSAGEix docs <message-ix:reporting>` about the stack.
 In short, for instance:
 
-- :mod:`message_ix` **must not** contain reporting code that references :py:`technology="coal_ppl"`, because not every model built on the MESSAGE framework will have a technology with this name.
-- Any model in the MESSAGEix-GLOBIOM family—built with :mod:`message_ix_models` and/or :mod:`message_data`—**should**, with few exceptions, have a :py:`technology="coal_ppl"`, since this appears in the common list of :ref:`technology-yaml`.
-  Reporting specific to this technology ID, *as it is represented* in this model family, should be in :mod:`message_ix_models` or user code.
+- :mod:`message_ix` **must not** contain reporting code that references :py:`technology="coal_ppl"`,
+  because not every model built on the MESSAGE framework will have a technology with this name.
+- Any model in the MESSAGEix-GLOBIOM family
+  —built with :mod:`message_ix_models` and/or :mod:`message_data`—
+  **should**, with few exceptions, have a :py:`technology="coal_ppl"`,
+  since this appears in the common list of :ref:`technology-yaml`.
+  Reporting specific to this technology ID,
+  *as it is represented* in this model family,
+  should be in :mod:`message_ix_models` or user code.
 
 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 :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.
+- :func:`~.report.prepare_reporter` populates a new :class:`~.message_ix.Reporter`
+  for a given :class:`.Scenario` with many tasks
+  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:
 
-  1. The module :mod:`message_ix_models.report.plot` defines :func:`.plot.callback` that adds standard plots to the Reporter.
-  2. The module :mod:`message_data.model.transport.report` defines :func:`~.message_data.model.transport.report.callback` that adds tasks specific to MESSAGEix-Transport.
-  3. The module :mod:`message_data.projects.navigate.report` defines :func:`~.message_data.projects.navigate.report.callback` that add tasks specific to the ‘NAVIGATE’ research project.
-
-  The callback (1) is always registered, because these plots are always applicable and can be expected to function correctly for all models in the family. In contrast, (2) and (3) **should** only be registered and run for the specific model variants for which they are developed/intended.
-
-  Modules with tailored reporting configuration **may** also be indicated on the :ref:`command line <report-cli>` by using the :program:`-m/--modules` option: :program:`mix-models report -m model.transport`.
-
-- A file :file:`global.yaml` file (in `YAML <https://en.wikipedia.org/wiki/YAML#Example>`_ format) contains a description of some of the reporting computations needed for a MESSAGE-GLOBIOM model.
-  :func:`~.report.prepare_reporter` uses the :doc:`configuration handlers <genno:config>` built into :mod:`genno` (and some extensions specific to :mod:`message_ix_models`) to handle the different sections of the file.
+  1. The module :mod:`message_ix_models.report.plot` defines :func:`.plot.callback`
+     that adds standard plots to the Reporter.
+  2. The module :mod:`message_ix_models.model.transport.report` defines :func:`~.transport.report.callback`
+     that adds tasks specific to the MESSAGEix-Transport model variant.
+  3. The module :mod:`message_ix_models.project.navigate.report` defines :func:`~.navigate.report.callback`
+       that add tasks specific to the ‘NAVIGATE’ research project.
+
+  The callback (1) is always registered,
+  because these plots are always applicable and can be expected to function correctly
+  for all models in the family.
+  In contrast, (2) and (3) **should** only be registered and run
+  for the specific model variants for which they are developed/intended.
+
+  Modules with tailored reporting configuration **may** also be indicated
+  on the :ref:`command line <report-cli>`
+  by using the :program:`-m/--modules` option:
+  :program:`mix-models report -m model.transport`.
+
+- A file :file:`global.yaml`
+  (in `YAML <https://en.wikipedia.org/wiki/YAML#Example>`_ format)
+  contains a description of some of the reporting computations
+  needed for a MESSAGE-GLOBIOM model.
+  :func:`~.report.prepare_reporter` uses the :doc:`configuration handlers <genno:config>`
+  built into :mod:`genno`
+  (and some extensions specific to :mod:`message_ix_models`)
+  to handle the different sections of the file.
 
 Features
 ========
 
-By combining these genno, ixmp, message_ix, and message_ix_models features, the following functionality is provided.
+By combining these genno, ixmp, message_ix, and message_ix_models features,
+the following functionality is provided.
 
 .. note:: If any of this does not appear to work as advertised, file a bug!
 
@@ -65,7 +92,8 @@ Units
 
 - Are read automatically for ixmp parameters.
 - Pass through calculations/are derived automatically.
-- Are recognized based on the definitions of non-SI units from `IAMconsortium/units <https://github.com/IAMconsortium/units/>`_.
+- Are recognized based on the definitions of non-SI units from
+  `IAMconsortium/units <https://github.com/IAMconsortium/units/>`_.
 - Are discarded when inconsistent.
 - Can be overridden for entire parameters:
 
@@ -133,7 +161,9 @@ Operators
       remove_ts
       share_curtailment
 
-   The following functions, defined elsewhere, are exposed through :mod:`.operator` and so can also be referenced by name:
+   The following functions, defined elsewhere,
+   are exposed through :mod:`.operator`
+   and so can also be referenced by name:
 
    .. autosummary::
 
@@ -255,11 +285,20 @@ Testing
 Continuous reporting
 --------------------
 
-As part of the :ref:`test-suite`, reporting is run on the same events (pushes and daily schedule) on publicly-available :doc:`model snapshots </api/model-snapshot>`.
-One goal of these tests *inter alia* is to ensure that adjustments and improvements to the reporting code do not disturb manually-verified model outputs.
-
-As part of the (private) :mod:`message_data` test suite, multiple workflows run on regular schedules; some of these include a combination of :mod:`message_ix_models`-based and :ref:`‘legacy’ reporting <report-legacy>`.
+As part of the :ref:`test-suite`, reporting is run on the same events
+(pushes and daily schedule)
+on publicly-available :doc:`model snapshots </api/model-snapshot>`.
+One goal of these tests *inter alia* is to ensure that adjustments
+and improvements to the reporting code
+do not disturb manually-verified model outputs.
+
+As part of the (private) :mod:`message_data` test suite,
+multiple workflows run on regular schedules;
+some of these include a combination of :mod:`message_ix_models`-based
+and :ref:`‘legacy’ reporting <report-legacy>`.
 These workflows:
 
 - Operate on specific scenarios within IIASA databases.
-- Create files in CSV, Excel, and/or PDF formats that are that are preserved and made available as 'build artifacts' via the GitHub Actions web interface and API.
+- Create files in CSV, Excel, and/or PDF formats
+  that are that are preserved and made available as 'build artifacts'
+  via the GitHub Actions web interface and API.