Add docs section on upgrading existing installations (#1233)

* Add section to docs on upgrading existing installations

* Align with the dir structure after f5cff94 (merge PR # 1237)

* Add back upgrade installation section after solving merge conflicts

* Restore asterisk needed for docs build to pass

docs/getting_started/index.rst

@@ -187,3 +187,43 @@ are located :ref:`here<getting_started/opt_dependencies:Optional Dependencies>`.
     :hidden:
 
     *
+
+Updating an existing installation
+---------------------------------
+
+When a new version is released, an IDAES installation can be updated without having to remove and reinstall it from scratch.
+
+The following steps describe how to upgrade an existing installation in-place,
+assuming that the installation was done using one of the methods described earlier in this section.
+
+.. warning:: If IDAES was installed in a dedicated environment (e.g. a Conda environment, or Python virtual environment), activate the environment before running any of these commands.
+
+1. Open a terminal and verify the currently installed version of IDAES::
+
+    idaes --version
+
+2. Install the upgraded version of the ``idaes-pse`` package using ``pip install``::
+
+    pip install --upgrade idaes-pse
+
+..
+
+    If a newer version of the ``idaes-pse`` package is available, the currently installed version will be removed and replaced by the newest available version.
+    Check again the IDAES version to verify that the upgrade was successful::
+
+        idaes --version
+
+3. Run the ``idaes get-extension`` command to install compiled binaries compatible with the newly upgraded IDAES version::
+
+    idaes get-extensions
+
+4. Finally, use the ``idaes get-examples`` command to install the most recent version of the IDAES examples compatible with the upgraded IDAES version.
+
+    .. warning:: If the examples target installation directory is not empty, its contents, including examples installed with a previous IDAES version and other files, **will be overwritten without warning**.
+        To avoid losing data, **it is strongly recommended that you make a backup copy of any existing examples directory** before proceeding.
+
+..
+
+    After creating a backup copy of the existing examples directory, run::
+
+        idaes get-examples