diff --git a/.github/workflows/docker.yaml b/.github/workflows/docker.yaml index 84829d033..29b9c3a84 100644 --- a/.github/workflows/docker.yaml +++ b/.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 diff --git a/docs/conf.py b/docs/conf.py index e630ecc60..98d6d5c9e 100644 --- a/docs/conf.py +++ b/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', -] \ No newline at end of file +] diff --git a/docs/environment.yaml b/docs/environment.yaml index 6d9b5aa7b..dd6600c95 100644 --- a/docs/environment.yaml +++ b/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 diff --git a/docs/installation.rst b/docs/installation.rst index 64771e442..359510307 100644 --- a/docs/installation.rst +++ b/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 `_ 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,