Add warnings/disclaimer for MACRO issues

i.e. #315, #316, #317, #318, #319, #320 stemming from #223

doc/source/api.rst

@@ -47,6 +47,7 @@ Support for R usage of the core classes is provided through the `reticulate`_ pa
 
 .. autoclass:: message_ix.Scenario
    :members:
+   :exclude-members: add_macro
    :show-inheritance:
    :inherited-members:
 
@@ -63,6 +64,7 @@ Support for R usage of the core classes is provided through the `reticulate`_ pa
 
       add_cat
       add_horizon
+      add_macro
       add_spatial_sets
       cat
       cat_list
@@ -76,6 +78,11 @@ Support for R usage of the core classes is provided through the `reticulate`_ pa
       vintage_and_active_years
       years_active
 
+   .. automethod:: add_macro
+
+      .. warning:: MACRO support via :meth:`add_macro` is **experimental** in message_ix 3.0 and may not function as expected on all possible |MESSAGEix| models.
+         See `a list of known and pending issues <https://github.com/iiasa/message_ix/issues?q=is%3Aissue+is%3Aopen+label%3Amacro>`_ on GitHub.
+
 
 Model classes
 -------------
@@ -131,7 +138,13 @@ Model classes
       **var_list**       :obj:`None`
       ================== ===
 
+
 .. autoclass:: MACRO
+   :members:
+   :show-inheritance:
+
+   .. autoattribute:: name
+
 
 .. autoclass:: MESSAGE_MACRO
    :members:
@@ -150,6 +163,8 @@ Model classes
    - **max_iteration** (:class:`int`, default 50): the maximum number of iterations between the two models.
      If the solution does not converge after this many iterations, the linked model run fails and no valid result is produced.
 
+   .. seealso:: :meth:`.Scenario.add_macro`
+
    .. autoattribute:: name
 
 .. autoclass:: GAMSModel

message_ix/core.py

@@ -448,6 +448,7 @@ def solve(self, model='MESSAGE', solve_options={}, **kwargs):
         super().solve(model=model, solve_options=solve_options, **kwargs)
 
     def add_macro(self, data, scenario=None, check_convergence=True, **kwargs):
+        """Add MACRO parametrization to the Scenario and calibrate."""
         # TODO document
         from .macro import EXPERIMENTAL, add_model_data, calibrate
         from .models import MACRO