Add section on section version management (#9)

Co-authored-by: Philip Hackstock <[email protected]>

conf.py

@@ -27,7 +27,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    "sphinx.ext.intersphinx",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -37,6 +39,12 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# -- Intersphinx -------------------------------------------------------------
+
+# Intersphinx configuration.
+intersphinx_mapping = {
+    "pyam": ("https://pyam-iamc.readthedocs.io/en/stable/", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 

scenario-databases.rst

@@ -19,7 +19,6 @@ including your view/submit/edit permissions, in the *Services* tab of the manage
 
 .. figure:: _static/ece-manager-screenshot.png
    :width: 600px
-   :align: left
 
    Screenshot of the "Overview" page of the `Scenario Services Manager`_
 
@@ -57,7 +56,15 @@ are required.
 Please follow the `Model registration user guide
 <https://nomenclature-iamc.readthedocs.io/en/stable/user_guide/model-registration.html>`_.
 
-Scenario submission
--------------------
+Scenario version management
+---------------------------
 
-Coming soon
+When submitting a scenario (a.k.a. "run") to an IIASA database instance with an already
+existing model-scenario combination, the database will save the new submission as a new version
+of that run. The **version number** is incremented automatically and the new version
+will be automatically set as **default version** for that model-scenario name.
+
+To select other (non-default) versions, you can use the "Switch to Advanced View" button
+in the scenario-selection tab of an IIASA Scenario Explorer or you can use the
+:code:`default_only=False` option of the function :func:`pyam.read_iiasa()`
+or the **ixmp4** package (`read the docs <https://docs.ece.iiasa.ac.at/ixmp4>`_).