Improve backwards compatibility documentation

doc/source/conf.py

@@ -41,6 +41,7 @@
     "sphinx_design",
     "sphinx_copybutton",
     "sphinx_jinja",
+    "sphinx.ext.extlinks",
 ]
 
 # Intersphinx mapping
@@ -70,6 +71,12 @@
     # type, unless multiple values are being returned"
 }
 
+extlinks = {
+    "MI_docs": (
+        "https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/Granta/v251/en/%s",
+        None,
+    ),
+}
 
 # static path
 html_static_path = ["_static"]
@@ -90,7 +97,7 @@
 )
 
 # Ignore ansys links for linkcheck
-linkcheck_ignore = ["https://www.ansys.com/"]
+linkcheck_ignore = ["https://www.ansys.com/", "https://ansyshelp.ansys.com"]
 
 # sphinx-jinja configuration
 jinja_contexts = {"package_versions_ctx": {}}

doc/source/getting_started.rst

@@ -1,50 +1,60 @@
 Getting started
 ===============
 
-The ``pygranta`` metapackage ensures compatibility between PyGranta packages and
-provides a convenient method for installing packages compatible with a specific
-release of Ansys Granta MI.
+The ``pygranta`` metapackage guarantees mutual compatibility between all PyGranta packages. The packages referenced by a
+``pygranta`` metapackage version are certified to be compatible with each other and with the corresponding Granta MI
+version.
 
-Most packages require access to an installation of Ansys Granta MI. For more
-information on getting a licensed copy of Ansys products, visit the `Ansys website <https://www.ansys.com/>`_.
+.. note::
+   The ``ansys-grantami-bomanalytics`` and ``ansys-grantami-bomanalytics-openapi`` versions included in the metapackage
+   are instead compatible with the corresponding version of *BoM Analytics Services*. BoM Analytics Services is the REST
+   API used by ``ansys-grantami-bomanalytics``, and is provided as part of the *Granta MI Restricted Substances and
+   Sustainability Reports* package. Multiple versions of the reports package are available for a single version of
+   Granta MI.
 
-************
-Installation
-************
+   The selected version of the reports package, and therefore the required version of ``ansys-grantami-bomanalytics``,
+   depends on the *Restricted Substances and Sustainability* database version.
 
-There are several ways of installing PyGranta depending on your use case, but
-the easiest is simply to run this command:
+   Refer to :MI_docs:`the Restricted Substances and Sustainability Install and Configuration guide
+   <RS_and_Sustainability_Install/rs_and_sustainability/planning_your_implementation_rsands.html>` for more details on
+   *Granta MI Restricted Substances and Sustainability Reports* versioning and installation.
 
-.. code:: bash
 
-   pip install pygranta
+Most packages require access to an installation of Ansys Granta MI. For more information on getting a licensed copy of
+Ansys products, visit the `Ansys website <https://www.ansys.com/>`_.
 
-This installs all the PyGranta packages for the latest released version of Granta MI.
+Installing the latest version
+-----------------------------
 
-If you are interested in **installing a specific version**, such as ``2023.2.0``, you
-can run a command like this one:
+To install the latest version of the ``pygranta`` metapackage, run:
 
 .. code:: bash
 
-   pip install pygranta==2023.2.0
+   pip install pygranta
+
+This installs all the PyGranta packages certified to be compatible with the latest released version of Granta MI.
 
-.. note::
-   The versions of ansys-grantami-bomanalytics and ansys-grantami-bomanalytics-openapi included in the metapackage
-   are compatible with that version of *BoM Analytics Services*, included with Granta MI Restricted
-   Substances and Sustainability Reports. Multiple versions of BoM Analytics Services are compatible with a single
-   version of Granta MI.
 
-You can always install PyGranta packages individually by following the installation
-instructions for each package. For example, the instructions for PyGranta
-RecordLists have you install it by running this command:
+Installing packages compatible with a specific version of Granta MI
+-------------------------------------------------------------------
+
+To install the version of the ``pygranta`` metapackage associated with a specific version of Granta MI, provide the
+version number during installation. For example, to install the version associated with Granta MI 2023 R2, specify the
+``pygranta`` metapackage version ``2023.2.0``:
 
 .. code:: bash
 
-   pip install ansys-grantami-recordlists
+   pip install pygranta==2023.2.0
+
+More detailed guidance on selecting package versions which are compatible with specific Granta MI versions is available
+on the :doc:`package_versions` page. This page also includes a list of all PyGranta packages associated with each
+``pygranta`` metapackage version.
+
+See `Versioning system`_ for more details on PyGranta package version numbers.
 
 
 User mode installation
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 Before installing the ``pygranta`` metapackage in user mode, ensure that you have the
 latest version of `pip <https://pypi.org/project/pip/>`_ by running this command:
@@ -67,8 +77,8 @@ can run a command like this one:
    python -m pip install pygranta==2023.2.0
 
 
-Offline mode installation
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Offline installation
+--------------------
 
 If you lack an internet connection on your installation machine, the
 recommended way of installing the ``pygranta`` metapackage is downloading the
@@ -94,6 +104,7 @@ using the same command as for Linux.
 
 Consider installing using a `virtual environment <https://docs.python.org/3/library/venv.html>`_.
 
+
 Versioning system
 -----------------
 

doc/source/package_versions.rst

@@ -1,14 +1,39 @@
+PyGranta and Granta MI compatibility
+====================================
+
+PyGranta packages have always been compatible with the Granta MI version they were delivered against.
+
+Starting with ``pygranta 2025.2.0`` (released with Granta MI 2025 R2), where possible, PyGranta packages are
+backwards compatible with all supported Granta MI versions at the time of release. This allows access to improvements
+and bug fixes without having to upgrade Granta MI.
+
+.. note::
+   Full backwards compatibility for all supported Granta MI versions is not always guaranteed. Check the README or
+   "Getting Started" guide for the individual PyGranta package to confirm the minimum required Granta MI version and for
+   installation instructions.
+
+If the latest PyGranta package version does not support the required Granta MI version, either:
+
+* Use previous versions of the PyGranta package documentation to check compatibility of previous package versions, or
+* Use the table in the `Package versions`_ section to identify the version of the PyGranta package released with the
+  required Granta MI version.
+
+In addition, forwards compatibility of PyGranta packages with future Granta MI releases is not guaranteed. PyGranta
+packages should always be upgraded following a Granta MI server upgrade.
+
+
 Package versions
-================
+----------------
 
-These tables map a PyGranta metapackage version to the individual PyGranta package included within it. In most cases,
-this can be used to determine which PyGranta package is compatible with a given version of Granta MI.
+These tables map a PyGranta metapackage version to the individual PyGranta package associated with it. This can be used
+to determine the **minimum** PyGranta package that is compatible with a given version of Granta MI. However, due to
+backwards compatibility, it may be possible to use more modern package versions.
 
 .. note::
-   The versions of ansys-grantami-bomanalytics and ansys-grantami-bomanalytics-openapi included in a metapackage version
-   are compatible with that version of *BoM Analytics Services*, included with Granta MI Restricted
-   Substances and Sustainability Reports. Multiple versions of BoM Analytics Services are compatible with a single
-   version of Granta MI.
+   The ``ansys-grantami-bomanalytics`` and ``ansys-grantami-bomanalytics-openapi`` versions included in the metapackage
+   are compatible with that version of *BoM Analytics Services*, included with Granta MI Restricted Substances and
+   Sustainability Reports. Multiple versions of BoM Analytics Services are compatible with a single version of Granta
+   MI.
 
 .. jinja:: package_versions_ctx
 

doc/source/user_guide.rst

@@ -6,11 +6,10 @@ User guide
 The ``pygranta`` metapackage itself is not used directly. Instead, it provides a bundle of
 PyGranta packages that are compatible with each other and with a given Granta MI release.
 
-The user guide for each PyGranta package provides general usage information.
+The user guide for each PyGranta package provides usage information specific to that package.
 
-********************
 PyGranta user guides
-********************
+--------------------
 
 .. grid:: 3
 
@@ -25,3 +24,5 @@ PyGranta user guides
     .. grid-item-card:: PyGranta JobQueue :material-regular:`work_history`
       :link: https://jobqueue.grantami.docs.pyansys.com/version/stable/user_guide/index.html
       :class-title: pyansys-card-title
+
+