Update install instructions

[glatterf42]

Closes #771, #819, and #835.

In particular, this PR splits ours install guide into a quick guide based on several assumptions and a full install guide with more background information.

This PR emphasizes pip as the preferred installation method rather than Anaconda based on personal experience and preference.

How to review

• Read the diff and note that the CI checks all pass.
• Look at the Installation and Full Installation Guide pages to check for correctness/style.

PR checklist

• [x] Continuous integration checks all ✅
• ~[ ] Add or expand tests; coverage checks both ✅~ Just documentation updates.
• [x] Add, expand, or update documentation.
• ~[ ] Update release notes.~ Just documentation updates.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 95.6%. Comparing base (bdf5747) to head (6c5bc91).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #843 +/- ## ======================================= - Coverage 95.6% 95.6% -0.1% ======================================= Files 46 46 Lines 4335 4333 -2 ======================================= - Hits 4145 4143 -2 Misses 190 190 ``` [see 2 files with indirect coverage changes](https://app.codecov.io/gh/iiasa/message_ix/pull/843/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=iiasa)

[glatterf42]

As mentioned by @adrivinca just now, we want to make sure that the quick-install pip steps include information about java. Either explicitly calling out the assumption that it's installed or saying how it can be installed.

[khaeru]

I pushed some commits based on the following observations/ideas:

• The pre-requisite knowledge is required for usage, so not specific to the quick install or full guide.
• Reduce reiteration of pre-requisite knowledge inline in the install instructions; instead, mention in the prereqs page and refer to that.
• Say "venv" when referring to venv, but "environment" when referring to a "conda environment". The conda docs do not use the word "virtual".
• Explain optional dependencies/extra requirements in 1 place instead of 3; deduplicate other footnotes and explanatory text using anchors and references.
• Move "Install from GitHub" from the quick install to the full guide. If the quick install aligns roughly with "Basic usage", we should not expect users to understand what Git is.
• Condense multiple paragraphs on the conditions for the Quick install to a list of bullets; move this up.
• Use :program: roles when referring to CLI programs, :mod: when referring to modules.
• Add sections on Python and Java to the full guide; collect scattered comments and notes about these.
• Add sections highlighting pip-vs-conda and venv choices; collect various texts related to these.
• Add an intro sentence to the full guide to explain how it differs from the Quick install.
• Renumber list items and footnotes.
• Start new sentences on new lines.

[glatterf42]

Are there any commits missing from this PR? Because your comment states that you want to move the "Install from GitHub" section from quick to full install, but it is still visible in the quick install section of the recent RTD build for this PR.

[glatterf42]

Also, there seem to be two notes in the RTD build output related to the latest changes:

/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/checkouts/843/doc/install-full.rst:41: WARNING: py:class reference target not found: JDBCBackend
/home/docs/checkouts/readthedocs.org/user_builds/iiasa-energy-program-message-ix/checkouts/843/doc/prereqs.rst:84: WARNING: undefined label: 'install-full'

[adrivinca]

thanks both for the great work. just a comment after reviewing the installation docs

Overall I think it looks good. I was a bit confused by this "quick" and "full" distinction, which gives the impression that if you do the quick install you don't have a full version of message_ix I would rename the "full" to "advanced", like in several software installation processes. The difference between the two installations seems simply that "full" is more advanced in terms of personalizing environments and the source (version) of the installation, plus the possibility to use R. But the quick install is also a full installation itself

[khaeru]

@glatterf42, since we both attempted to do the rename at the same time, we have diverged branches. I also made a few further copyedits, and added to the release notes, as these are substantial changes to the install instructions.

I've pushed to https://github.com/iiasa/message_ix/tree/update/install-instructions-2024-05 —can you incorporate these on your branch, please? Either pull that and force-push to your branch associated with the PR, or cherry-pick the commits, as you please.