Create "Quick starting guide to running MESSAGEix-GLOBIOM" for occasional users

[glatterf42]

This PR supersedes https://github.com/iiasa/message_data/pull/312 and thus fixes https://github.com/iiasa/message_data/issues/287 once we merge it. The main reason for migrating this PR is that we now have a snapshot of a global baseline model available at Zenodo, so there might be demand for having these instructions be public, too.

Thanks a lot to @jkikstra for writing up the original issue and to @LauWien for starting the original PR.

After going through the original material, I think almost everything should be included in the new docs except for some Common Issue that @jkikstra reported:

• a GAMS error the first time you are doing scenario.solve():

com.gams.api.GAMSException: com.gams.api.GAMSException: GAMS system directory is both not specified and not found from your environment!

FIX: You have not yet set up your GAMSDIR and Path environment variables correctly. Set GAMSDIR for instance to "C:\GAMS\35; C:\GAMS\35\gbin" and add to Path "%GAMSDIR%"

• a GAMS license error the first time you are doing scenario.solve():

![image](https://user-images.githubusercontent.com/46967503/152387421-c16464bb-d985-4221-b1bc-8f8e0db78288.png)

FIX: locate your "gamslice.txt" (if you don't have this, ask someone else about GAMS license files) and place it in your GAMS folder (e.g. "C:\GAMS\35"). After that, copy the text of that file to your clipboard, then open GAMS Studio, go to Help -->GAMS Licensing, which should then give a pop-up that will solve all of your problems.

• a GAMS execution error relating to the MACRO iteration, e.g.

ixmp.model.base.ModelError: GAMS errored with return code 3:
    There was an execution error
For details, see the terminal output above, plus:
Listing   : C:\Users\kikstra\Miniconda3\envs\mdl\lib\site-packages\message_ix\model\MACRO_run.lst
Input data: C:\Users\kikstra\Miniconda3\envs\mdl\lib\site-packages\message_ix\model\data\MsgData_mdle-run-jsk_ssp2_macro.gdx

FIX: To figure out what's up, we can check the log file (*.lst). Open the gamside application and load the "MACRO_run.lst", and then search (Ctrl-F, then F3 for next) for "error" until you see something that helps you out.

The first one shouldn't happen if users follow the install instructions closely; the second one seems rather general, so should maybe make it into message_ix if we want to record it, but isn't directly related to install issues; the third one might also need to go to message_ix and is also only related to running the code without errors.

How to review

@gidden, since you were interested in merging https://github.com/iiasa/message_data/pull/312, could you please check that no information in there is incorrect?

@yiyi1991, @daymontas1: since you have started recently, maybe you could take a look at the new docs and see if they would have been helpful for you. If you notice anything that seems to be missing, please leave a comment :)

FYI @khaeru, I might enable building the docs on RTD for this PR to make it easier to check the new ones.

• Read the diff and note that the CI checks all pass.
• Look at the following pages of the documentation:
  • Installation
  • Quickstart

PR checklist

• Continuous integration checks all ✅
• [ ] Add or expand tests; coverage checks both ✅ Only updating docs.
• Add, expand, or update documentation.
• Update doc/whatsnew.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 76.7%. Comparing base (3526681) to head (a01f61a).
Report is 1 commits behind head on main.

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #157   +/-   ##
=====================================
  Coverage   76.7%   76.7%           
=====================================
  Files        112     112           
  Lines       7154    7154           
=====================================
  Hits        5494    5494           
  Misses      1660    1660           

[glatterf42]

Curious as to why the tests fail to read the snapshot. Is there some kind of rate limit with Zenodo that we are hitting?

[khaeru]

Overall this seems like a good start!

Things that jump out at a quick skim:

• Several sections of this appear to be simply copy-pasted from other docs, for instance the instructions on how to configure the connection details for a particular ixmp Platform.

  We should instead link directly to the relevant sections and only add context-specific information. We could also update or expand those in-place. Duplicated text means extra work to remember to keep both in sync in the future.

• In several places where such links are already used, they are written a ReST URL links to https://docs.messageix.org/… . These should be InterSphinx links instead. I'll comment one example.

Curious as to why the tests fail to read the snapshot. Is there some kind of rate limit with Zenodo that we are hitting?

Any test (or CI step) that makes a network query is vulnerable to transient connection issues: DNS lookups, the server responding, completing the query, etc. Some of these are not about our code but about the availability and steadiness of Zenodo's services. When we try this enough times, a low failure probability can yield frequent single failures.

[khaeru]

This is a direct URL link:

`contributing to development <https://docs.messageix.org/en/latest/contributing.html>`_

Wherever possible we use intersphinx links, which are more reliable:

:doc:`message-ix:contributing`

• The prefixes before the : can be viewed in conf.py:

  message-ix-models/doc/conf.py

  Lines 134 to 150 in 583d3e9

  	intersphinx_mapping = {
  	"click": ("https://click.palletsprojects.com/en/8.1.x/", None),
  	"genno": ("https://genno.readthedocs.io/en/stable", None),
  	"ixmp": ("https://docs.messageix.org/projects/ixmp/en/latest/", None),
  	"message-ix": ("https://docs.messageix.org/en/latest/", None),
  	"m-data": (
  	f"https://{_token}:@docs.messageix.org/projects/models-internal/en/latest/",
  	# Use a local copy of objects.inv, if the user has one
  	(local_inv("message_data"), None),
  	),
  	"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
  	"pint": ("https://pint.readthedocs.io/en/stable/", None),
  	"pooch": ("https://www.fatiando.org/pooch/latest/", None),
  	"pytest": ("https://docs.pytest.org/en/stable/", None),
  	"python": ("https://docs.python.org/3/", None),
  	"sdmx": ("https://sdmx1.readthedocs.io/en/stable/", None),
  	}

• The docs show how to retrieve and inspect the list of :doc:, :ref: etc. targets available from a given other project.

[glatterf42]

The command to retrieve the targets doesn't readily work for me. If I pass a directory to it, it gives me an IsADirectoryError; if I pass in a single file, I receive varying ValueErrors because the inventory header is invalid; and the same is true if I pass in a URL to a page of our docs.
I guess I'll look up targets manually.

[khaeru]

Notice that in the example in the Sphinx docs, …/objects.inv is appended. This happens automatically during sphinx-build, but not for the helper command.

So for instance: python -m sphinx.ext.intersphinx https://pint.readthedocs.io/en/stable/objects.inv, where "https://pint.readthedocs.io/en/stable/" is the base URL appearing in conf.py. I usually pipe the result to less to be able to page up and down.

[glatterf42]

Right, it needs to be the objects.inv file that I can find in e.g. ixmp/doc/_build/.

[glatterf42]

If I understand correctly, intersphinx tries to resolve an undefined reference like :doc:'installation' by going through all other linked sources, so I tried following the official guide and linked external reference in this way: :external+message-ix:doc:'installation'.

[yiyi1991]

This merge to #287 is super helpful. Thank you.
Maybe we can also shortly mention the required GMAS license version (v29+ I believe) if it is not mentioned elsewhere.

[glatterf42]

The docs build might not work yet because I already included some docs labels from message_ix that are only yet introduced with iiasa/message_ix#805.

Apart from that, I rewrote parts of the new docs to avoid duplicate information, but there's actually not a lot of copy-paste in here to begin with, so it's still the same in large parts.

[glatterf42]

Maybe we can also shortly mention the required GMAS license version (v29+ I believe) if it is not mentioned elsewhere.

We already do that: https://docs.messageix.org/en/stable/install.html

[glatterf42]

Now, there are only the two links not working that rely on the new labels in message_ix. Even though our intersphinx_mapping refers to "https://docs.messageix.org/en/latest/" for message-ix, I suspect this is because our requirements.txt installs message_ix==3.8.0.

Also, there's an abundance of unrecognized/unresolvable references in other documents and it would likely improve our docs a lot if we fixed them, but this is a topic for another PR.

[glatterf42]

@jkikstra This has been a long time ago for you, but at today's MESSAGE meeting we concluded that it would probably still be good for you to take a look at the final product and tell us if you like it.

[khaeru]

I added a commit to the branch with some copyedits and additions.

LGTM once checks pass!

[glatterf42]

Thanks :)