Merge pull request #497 from OpenFreeEnergy/feat/add_version_to_docs

Tell users to install the latest version of openfe

.github/workflows/docker.yaml

@@ -126,3 +126,4 @@ jobs:
           singularity run ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif pytest --pyargs openfecli --pyargs openfe -v -n auto
           echo ${{ secrets.GITHUB_TOKEN }} | singularity remote login -u ${{ secrets.GHCR_USERNAME }} --password-stdin oras://ghcr.io
           singularity push ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif oras://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.latest-version.outputs.VERSION }}-apptainer
+          singularity push ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif oras://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest-apptainer

docs/conf.py

@@ -12,6 +12,8 @@
 #
 import os
 import sys
+from importlib.metadata import version
+from packaging.version import parse
 sys.path.insert(0, os.path.abspath('../'))
 
 
@@ -22,7 +24,7 @@
 project = 'OpenFE'
 copyright = '2022, The OpenFE Development Team'
 author = 'The OpenFE Development Team'
-
+version = parse(version("openfe")).base_version
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -101,4 +103,4 @@
 html_static_path = ['_static']
 html_css_files = [
     'css/custom.css',
-]
+]

docs/environment.yaml

@@ -4,15 +4,16 @@ channels:
 - https://conda.anaconda.org/conda-forge
 dependencies:
 - autodoc-pydantic
+- openff-models>=0.0.5
 - openff-toolkit >=0.13.0
 - openff-units
 - openmm
+- packaging
 - plugcli
 - pydata-sphinx-theme
 - python=3.9
 - sphinx
 - sphinx-click
-- openff-models>=0.0.5
 - tqdm
 - pip:
   - sphinx-design

docs/installation.rst

@@ -96,9 +96,11 @@ commands it suggests.
 You should then close your current session and open a fresh login to ensure
 that everything is properly registered.
 
-Next we will create an environment called ``openfe_env`` with the ``openfe`` package and all required  dependencies ::
+Next we will create an environment called ``openfe_env`` with the ``openfe`` package and all required dependencies
 
-  $ mamba create -n openfe_env openfe
+.. parsed-literal::
+
+  $ mamba create -n openfe_env openfe=\ |version|
 
 Now we need to activate our new environment ::
 
@@ -109,9 +111,11 @@ Now we need to activate our new environment ::
 
    Installing on newer Macs with Apple Silicon requires a creating an x86_64
    environmment, as one of our requirements is not yet available for Apple
-   Silicon. Run the following modified commands::
+   Silicon. Run the following modified commands
+
+   .. parsed-literal:: 
 
-      CONDA_SUBDIR=osx-64 mamba create -n openfe_env openfe
+      CONDA_SUBDIR=osx-64 mamba create -n openfe_env openfe=\ |version|
       mamba activate openfe_env
       mamba env config vars set CONDA_SUBDIR=osx-64
 
@@ -135,18 +139,18 @@ Single file installers are available for x86_64 Linux and MacOS.
 They are attached to our `releases on GitHub <https://github.com/OpenFreeEnergy/openfe/releases>`_ and can be downloaded with a browser or ``curl`` (or similar tool).
 For example, the linux installer can be downloaded with ::
 
-  $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v0.7.4/OpenFEforge-0.7.4-Linux-x86_64.sh
+  $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/OpenFEforge-Linux-x86_64.sh
 
 And the MacOS installer ::
 
-  $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v0.7.4/OpenFEforge-0.7.4-MacOSX-x86_64.sh 
+  $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/OpenFEforge-MacOSX-x86_64.sh
 
 The single file installer contains all of the dependencies required for ``openfe`` and does not require internet access to use.
 Both ``conda`` and ``mamba`` are also available in the environment created by the single file installer and can be used to install additional packages.
 The installer can be installed in batch mode or interactively  ::
   
-  $ chmod +x ./OpenFEforge-0.7.4-Linux-x86_64.sh # Make installer executable
-  $ ./OpenFEforge-0.7.4-Linux-x86_64.sh # Run the installer
+  $ chmod +x ./OpenFEforge-Linux-x86_64.sh # Make installer executable
+  $ ./OpenFEforge-Linux-x86_64.sh # Run the installer
 
 Example installer output is shown below (click to expand "Installer Output")
 
@@ -334,16 +338,25 @@ Containers
 We provide an official docker and apptainer (formally singularity) image.
 The docker image is tagged with the version of ``openfe`` on the image and can be pulled with ::
 
-  $ docker pull ghcr.io/openfreeenergy/openfe:0.7.4
+  $ docker pull ghcr.io/openfreeenergy/openfe:latest
 
 The apptainer image is pre-built and can be pulled with ::
 
-  $ singularity pull oras://ghcr.io/openfreeenergy/openfe:0.7.4-apptainer
+  $ singularity pull oras://ghcr.io/openfreeenergy/openfe:latest-apptainer
+
+.. warning::
+
+   For production use, we recommend using version tags to prevent disruptions in workflows e.g.
+
+   .. parsed-literal::
+
+     $ docker pull ghcr.io/openfreeenergy/openfe:\ |version|
+     $ singularity pull oras://ghcr.io/openfreeenergy/openfe:\ |version|-apptainer
 
 We recommend testing the container to ensure that it can access a GPU (if desired).
 This can be done with the following command ::
 
-  $ singularity run --nv openfe_0.7.4-apptainer.sif python -m openmm.testInstallation
+  $ singularity run --nv openfe_latest-apptainer.sif python -m openmm.testInstallation
   
   OpenMM Version: 8.0
   Git Revision: a7800059645f4471f4b91c21e742fe5aa4513cda
@@ -367,11 +380,11 @@ Your output may produce different values for the forces, but should list the CUD
 
 You can access the ``openfe`` CLI from the singularity image with ::
 
-  $ singularity run --nv openfe_0.7.4-apptainer.sif openfe --help
+  $ singularity run --nv openfe_latest-apptainer.sif openfe --help
 
 To make sure everything is working, run the tests ::
 
-  $ singularity run --nv openfe_0.7.4-apptainer.sif pytest --pyargs openfe openfecli
+  $ singularity run --nv openfe_latest-apptainer.sif pytest --pyargs openfe openfecli
 
 The test suite contains several hundred individual tests. This will take a
 few minutes, and all tests should complete with status either passed,