Fix typos regarding FindPython3 CMake module hint.

[alexxy/gromacs.git] / docs / gmxapi / userguide / install.rst

diff --git a/docs/gmxapi/userguide/install.rst b/docs/gmxapi/userguide/install.rst
index f7058818ca3dd18830adf5a57585aa58758b8719..8588156a48b3d85140459260e93457ec49e99d3f 100644 (file)
--- a/docs/gmxapi/userguide/install.rst
+++ b/docs/gmxapi/userguide/install.rst
@@ -196,16 +196,21 @@ Documentation build requirements
 
 See :ref:`gmxapi_package_documentation`
 
-.. _testing_requirements:
+.. _testing requirements:
 
 Testing requirements
 --------------------
 
+Note that the test suite is only available in the GROMACS source tree.
+(It is not part of the installed package.)
+Acquire the GROMACS sources with :command:`git` or by downloading an archive, as documented elsewhere.
+
 Testing is performed with `pytest <https://docs.pytest.org/en/latest/>`_.
-Tests also require numpy_.
-You can probably install both with pip_::
 
-    pip install pytest numpy
+:file:`python_packaging/requirements-test.txt` lists additional requirements for testing.
+With pip_::
+
+    pip install -r python_packaging/requirements-test.txt
 
 To test the full functionality also requires an MPI parallel environment.
 You will need the mpi4py_ Python package and an MPI launcher
@@ -361,10 +366,18 @@ GROMACS against and building with compatible compilers.
 Install the latest version of gmxapi
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Fetch and install the latest version of gmxapi from the Python Packaging Index::
+Fetch and install the latest official version of gmxapi from the Python Packaging Index::
 
+    # Get the latest official release.
     pip install gmxapi
 
+The `PyPI repository <https://pypi.org/project/gmxapi/#history>`_
+may include pre-release versions,
+but :command:`pip` will ignore them unless you use the ``--pre`` flag::
+
+    # Get the latest version, including pre-release versions.
+    pip install --pre gmxapi
+
 If :command:`pip` does not find your GROMACS installation, use one of the following
 environment variables to provide a hint.
 
@@ -485,14 +498,14 @@ extract Python docstrings.
 
 Sometimes the build environment can choose a different Python interpreter than
 the one you intended.
-You can set the ``Python3_ROOT`` or ``CMAKE_PREFIX_PATH`` CMake variable to
+You can set the ``Python3_ROOT_DIR`` or ``CMAKE_PREFIX_PATH`` CMake variable to
 explicitly choose the Python installation or *venv* directory.
 
 If you use pyenv or pyenv-virtualenv to dynamically manage your Python version,
 you can help identify a particular version with ``pyenv version-name`` and the
 directory with ``pyenv prefix {version}``. For example::
 
-    -DPython3_ROOT=$(pyenv prefix $(pyenv version-name))
+    -DPython3_ROOT_DIR=$(pyenv prefix $(pyenv version-name))
 
 Docker web server
 -----------------
@@ -506,12 +519,41 @@ https://hub.docker.com/r/gmxapi/docs for more information.
     Document sample_restraint package. Reference issue
     `3027 <https://gitlab.com/gromacs/gromacs/-/issues/3027>`_
 
+Testing
+=======
+
+Note `testing requirements`_ above.
+
+After installing the :py:mod:`gmxapi` Python package,
+you can run the Python test suite from the GROMACS source tree.
+Example::
+
+    # Assuming you are in the root directory of the repository:
+    pytest python_packaging/src/test/
+
+Refer to :file:`python_packaging/README.md` for more detailed information.
+
 .. _gmxapi install troubleshooting:
 
 Troubleshooting
 ===============
 
+AttributeError: module 'enum' has no attribute 'IntFlag'
+--------------------------------------------------------
+
+If you had older versions of some of the dependencies installed,
+you might have picked up a transitive dependency on the ``enum34`` package.
+Try::
+
+    pip uninstall -y enum34
+
+and see if that fixes the problem. If not, try a fresh virtual environment
+(see above) to help narrow down the problem before you
+`open an issue <https://gitlab.com/gromacs/gromacs/-/issues/>`_.
+
 Couldn't find the ``gmxapi`` support library?
+---------------------------------------------
+
 If you don't want to "source" your :ref:`GMXRC <getting access to |Gromacs|>` file, you
 can tell the package where to find a gmxapi compatible GROMACS installation with
 ``gmxapi_DIR``. E.g. ``gmxapi_DIR=/path/to/gromacs pip install .``