Resolving documentation build warnings
- 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
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