message_ix.macro lacks minimal documentation

[khaeru]

To complete the code added in #223, one or more PRs are needed to document the message_ix.macro module, including:

• both docstrings and in-line comments for:
  • core.Scenario.add_macro()
  • macro constants: DATA_KEY, UNITS, MACRO_ITEMS, MACRO_DATA_FOR_DERIVATION, VERIFY_INPUT_DATA.
  • macro._validate_data()
  • macro.Calculate (i.e. init)
  • macro.Calculate.read_data
  • macro.Calculate._clean_model_data
  • macro.Calculate.derive_data
  • macro.Calculate._growth
  • macro.Calculate._rho
  • macro.Calculate._gdp0
  • macro.Calculate._k0
  • macro.Calculate._total_cost
  • macro.Calculate._price
  • macro.Calculate._demand
  • macro.Calculate._bconst
  • macro.Calculate._aconst
  • macro.add_model_data
  • macro.calibrate
  • All tests in test_macro.py
• Explanatory text for new GAMS items such as these.
• A new page in the Sphinx docs, including:
  • autodoc of all of the above.
  • Clear advertisement of any current limitations of the code, such as (per inline comment) all demands and prices are assumed to be on level='useful'.

[khaeru]

Postponing to after v3.0.

[khaeru]

At the moment, users can look at test_macro.py for some examples of the code in action as part of the test suite.

[khaeru]

No one was assigned to do this by the feature freeze for v3.2.0, so we postpone to v3.3 (or later).

[khaeru]

No one was assigned to do this by the feature freeze for v3.3.0, so we postpone to v3.4 (or later).

[LauWien]

Some documentation is already implemented in PR #327 (probably will be merged after this release). As for the rest, no one was assigned to do this for v3.4.0, so we postpone to v3.5 (or later).

[LauWien]

No one was assigned to do this by the feature freeze for v3.5.0, so we postpone to v3.6 (or later).

[khaeru]

Removing the milestone entirely. It can be re-added if/when the team decides to schedule/assign the work.