Minimal changes for #277

- Format docstring according to code style, rewrap.
- Add type hints.
- Ensure the module appears in the docs.
- Add (incomplete) tests for all parts of the code.

Author: khaeru

doc/api/tools.rst

@@ -6,21 +6,25 @@ General purpose modeling tools (:mod:`.tools`)
 - Codes for retrieving data from specific data sources and adapting it for use with :mod:`message_ix_models`.
 - Codes for modifying scenarios; although tools for building models should go in :mod:`message_ix_models.model`.
 
+.. currentmodule:: message_ix_models.tools
+
 On other pages:
 
 - :doc:`tools-costs`
 
+.. autosummary::
+   :toctree: _autosummary
+   :template: autosummary-module.rst
+   :recursive:
+
+   res_marg
+
 On this page:
 
 .. contents::
    :local:
    :backlinks: none
 
-.. currentmodule:: message_ix_models.tools
-
-.. automodule:: message_ix_models.tools
-   :members:
-
 .. currentmodule:: message_ix_models.tools.exo_data
 
 Exogenous data (:mod:`.tools.exo_data`)

message_ix_models/tests/tools/test_res_marg.py

@@ -0,0 +1,15 @@
+import pytest
+
+from message_ix_models.tools.res_marg import main
+
+
+@pytest.mark.xfail(reason="Incomplete test")
+def test_cli() -> None:
+    # TODO Complete
+    assert False
+
+
+@pytest.mark.xfail(reason="Incomplete test")
+def test_main() -> None:
+    # TODO Complete
+    main()

message_ix_models/tools/res_marg.py

@@ -1,24 +1,30 @@
+"""Update the reserve margin."""
+
 import argparse
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from message_ix import Scenario
+
 
+def main(scen: "Scenario", contin: float = 0.2) -> None:
+    """Update the reserve margin.
+
+    For a given scenario, regional reserve margin (=peak load factor) values are updated
+    based on the electricity demand in the industry and res/comm sector.
 
-def main(scen, contin=0.2):
-    """Updates the reserve margin.
-    For a given scenario, regional reserve margin (=peak load factor) values
-    are updated based on the electricity demand in the industry and res/comm
-    sector.
     This is based on the approach described in Johnsonn et al. (2017):
-    DOI: https://doi.org/10.1016/j.eneco.2016.07.010
-    (see section 2.2.1. Firm capacity requirement)
+    DOI: https://doi.org/10.1016/j.eneco.2016.07.010 (see section 2.2.1. Firm capacity
+    requirement)
 
     Parameters
     ----------
-    scen : :class:`message_ix.Scenario`
-        scenario to which changes should be applied
-    contin : float
-        Backup capacity for contingency reasons as percentage of peak capacity
-        (default 20%)
+    scen :
+        Scenario to which changes should be applied.
+    contin :
+        Backup capacity for contingency reasons as percentage of peak capacity (default
+        20%).
     """
-
     demands = scen.par("demand")
     demands = (
         demands[demands.commodity.isin(["i_spec", "rc_spec"])]