iiasa / iiasa/message_ix

Resolving documentation build warnings

Open
#758 4 comments 0 reactions 0 assignees View on GitHub
bug docs
Dominant language
Jupyter Notebook
Stars
150
Forks
178
Avg merge
17h 32m
Merged PRs (30d)
2

Description

As mentioned in #757, our docs are [building successfully](https://readthedocs.com/projects/iiasa-energy-program-message-ix/builds/1820820/), though with several warnings:
```bash
reading sources... [ 2%] api
Cannot locate code for 'message_ix.models.DEFAULT_CPLEX_OPTIONS' or parent class/module
Cannot locate code for 'message_ix.models.MESSAGE_ITEMS' or parent class/module
Cannot locate code for 'message_ix.macro.MACRO_ITEMS' or parent class/module
```
```bash
reading sources... [100%] whatsnew

/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/checkouts/latest/doc/api.rst:24: WARNING: autosummary: failed to import ixmp.testing.make_dantzig.
Possible hints:
* AttributeError: module 'ixmp' has no attribute 'testing'
* ModuleNotFoundError: No module named 'pytest'
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/checkouts/latest/doc/reporting.rst:282: WARNING: autosummary: failed to import genno.compat.pyam.computations.as_pyam.
Possible hints:
* AttributeError: module 'genno.compat.pyam' has no attribute 'computations'
* AttributeError: module 'message_ix.reporting.computations' has no attribute 'genno'
* ModuleNotFoundError: No module named 'genno.compat.pyam.computations'
* ModuleNotFoundError: No module named 'message_ix.reporting.computations.genno'; 'message_ix.reporting.computations' is not a package
```
```bash
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.add:8: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.add:8: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.check_keys:1: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.check_keys:19: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.infer_keys:1: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.infer_keys:1: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.infer_keys:17: ERROR: Undefined substitution referenced: "KeyLike".
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.infer_keys:18: ERROR: Undefined substitution referenced: "KeyLike".
```
```bash
writing output... [100%] whatsnew

/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.cache:3: WARNING: unknown document: 'cache'
generating indices... /home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/envs/latest/lib/python3.11/site-packages/message_ix/reporting/__init__.py:docstring of genno.core.computer.Computer.configure:8: WARNING: unknown document: 'config'
```

These warnings and errors probably mean that some aspects of our framework are not documented as expected, though most of that seems to be due to erroneous links. We should investigate how these links ought to look so that our documentation can be complete (again).

Possible sources for e.g. `ixmp.testing` missing:

- ixmp might have had a `testing` module that got renamed
- ixmp might have a `testing` module, but the docs don't have it
- the ixmp version installed in the RTD process is a version that doesn't have access to `testing`

Contributor guide

Open the contributing guide

Research direction

Start with the Read the Docs build output and the referenced doc/api.rst and doc/reporting.rst locations. Trace the missing ixmp.testing, genno.compat.pyam.computations.as_pyam, KeyLike, cache, and config references to determine whether the documentation or installed dependencies are outdated. Done means the documented APIs resolve and the reported warnings and errors are addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.