Update docs, release notes for #972

Author: khaeru

RELEASE_NOTES.rst

@@ -1,6 +1,24 @@
 Next release
 ============
 
+Migration notes
+---------------
+
+Adjust any imports like the following:
+
+.. code-block:: python
+
+    from message_ix.models import DIMS, Item, MACRO, MESSAGE, MESSAGE_MACRO
+
+…to:
+
+.. code-block:: python
+
+    from message_ix.common import DIMS, Item
+    from message_ix.macro import MACRO
+    from message_ix.message import MESSAGE
+    from message_ix.message_macro import MESSAGE_MACRO
+
 All changes
 -----------
 
@@ -20,6 +38,13 @@ All changes
   - Revise :ref:`equation_commodity_balance_aux` to include input and output flows based on |CAP| and |CAP_NEW|.
   - New :class:`.MESSAGE` / :meth:`.Scenario.solve` option :py:`cap_comm=True` to enable this representation.
 
+- The former module :py:`message_ix.models` is split to distinct submodules (:pull:`972`):
+
+  - :mod:`message_ix.common` includes :class:`.GAMSModel` and related code.
+  - :mod:`message_ix.macro` includes :class:`.MACRO`.
+  - :mod:`message_ix.message` includes :class:`.MESSAGE`.
+  - :mod:`message_ix.message_macro` includes :class:`.MESSAGE_MACRO`.
+
 - Document the :ref:`minimum version of Java <install-java>` required for :class:`ixmp.JDBCBackend <ixmp.backend.jdbc.JDBCBackend>` (:pull:`962`).
 - Improve type hinting (:pull:`963`).
 

doc/api.rst

@@ -129,27 +129,28 @@ The full API is also available from R; see :doc:`rmessageix`.
 Model classes
 -------------
 
-.. currentmodule:: message_ix.models
+.. currentmodule:: message_ix
 
 .. autosummary::
 
-   MESSAGE
-   MACRO
-   MESSAGE_MACRO
-   GAMSModel
-   DEFAULT_CPLEX_OPTIONS
-   Item
-   ItemType
+   ~message_ix.message.MESSAGE
+   ~message_ix.macro.MACRO
+   ~message_ix.message_macro.MESSAGE_MACRO
+   ~message_ix.common.GAMSModel
+   ~message_ix.common.DEFAULT_CPLEX_OPTIONS
+   ~message_ix.common.Item
+   ~ixmp.backend.ItemType
 
-.. autodata:: DEFAULT_CPLEX_OPTIONS
+.. autodata:: message_ix.common.DEFAULT_CPLEX_OPTIONS
 
    These configure the GAMS CPLEX solver (or another solver, if selected); see `the solver documentation <https://www.gams.com/latest/docs/S_CPLEX.html>`_ for possible values.
 
-.. autoclass:: GAMSModel
+.. autoclass:: message_ix.common.GAMSModel
    :members:
    :exclude-members: defaults
 
-   The :class:`.MESSAGE`, :class:`MACRO`, and :class:`MESSAGE_MACRO` child classes encapsulate the GAMS code for the core MESSAGE (or MACRO) mathematical formulation.
+   The :class:`.MESSAGE`, :class:`.MACRO`, and :class:`.MESSAGE_MACRO` child classes
+   encapsulate the GAMS code for the core MESSAGE (or MACRO) mathematical formulation.
 
    The class receives `model_options` via :meth:`.Scenario.solve`. Some of these are passed on to the parent class :class:`ixmp.model.gams.GAMSModel` (see there for a list); others are handled as described below.
 
@@ -307,12 +308,10 @@ Model classes
    .. autoattribute:: items
       :no-value:
 
-.. autodata:: DIMS
-.. autoclass:: Item
+.. autodata:: message_ix.common.DIMS
+.. autoclass:: message_ix.common.Item
    :members:
 
-.. currentmodule:: message_ix.macro
-
 .. _utils:
 
 Utility methods