Improve accessibility of pytest documentation.

* Update gmxapi install.rst.
* Consolidate (and prune) some README.md content in
  python_packaging subdirectory.

Also ref #3706

Fixes #3702

diff --git a/docs/gmxapi/userguide/install.rst b/docs/gmxapi/userguide/install.rst
index 65d80d88186fed2d510dc680aabc4cf649662d8e..7e96486f7f45f467a73cdbcfebaef108d0599422 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
@@ -514,6 +519,20 @@ 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

diff --git a/python_packaging/README.md b/python_packaging/README.md
index faa48c6a165ee33aa48809accd37b07ad768b597..e6824acb443f86a8fe07ae3863e0f6b4696c4b7c 100644 (file)
--- a/python_packaging/README.md
+++ b/python_packaging/README.md
@@ -155,3 +155,42 @@ satisfying dependencies for a new virtualenv does not require network access or
 Some dependencies (notably, a Python installation itself) may require some fiddling
 with the XCode SDK.
 https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes#3035624
+
+# Tests for gmxapi Python packages distributed with GROMACS
+
+## Requirements
+
+Python tests use the `unittest` standard library module and the `unittest.mock`
+submodule, included in Python 3.3+.
+
+The additional `pytest` package allows tests to be written more easily and
+concisely, with easier test fixtures (through decorators), log handling, and
+other output handling.
+
+## Files
+
+Python files beginning with `test_` are collected by the Python testing
+framework during automatic test discovery.
+
+`conftest.py` and `pytest.ini` provide configuration for `pytest`.
+
+## Usage
+
+For basic tests, install the Python package(s) (presumably into a virtualenv),
+then use the `pytest` executable to run these tests against the installed
+package(s).
+
+`pytest $LOCAL_REPO_DIR/python_packaging/src/test`
+
+where `$LOCAL_REPO_DIR` is the path to the local copy of the GROMACS source repository.
+
+For multi-process tests, run with an MPI execution wrapper and the `mpi4py` module.
+
+`mpiexec -n 2 python -m mpi4py -m pytest $LOCAL_REPO_DIR/python_packaging/test`
+
+## Controlling output
+
+Refer to pytest documentation for command line options to control the type and detail of output.
+Some high level overview and basic tasks are online at https://docs.pytest.org/en/3.9.3/usage.html
+but you should run `pytest -h` in a terminal to get the complete set of available options
+(in particular, note *log_cli* and *log_level*).

diff --git a/python_packaging/test/README.md b/python_packaging/test/README.md
deleted file mode 100644 (file)
index 413faf8..0000000
--- a/python_packaging/test/README.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Tests for gmxapi Python packages distributed with GROMACS
-
-Potentially longer-running than the unit tests in the Python package directory
-and broader in scope. Intended to include more thorough and complete integration
-testing than in the `acceptance` subdirectory.
-
-## Requirements
-
-Python tests use the `unittest` standard library module and the `unittest.mock`
-submodule, included in Python 3.3+.
-
-The additional `pytest` package allows tests to be written more easily and
-concisely, with easier test fixtures (through decorators), log handling, and
-other output handling.
-
-## Files
-
-Python files beginning with `test_` are collected by the Python testing
-framework during automatic test discovery.
-
-`conftest.py` and `pytest.ini` provide configuration for `pytest`.
-
-Tests are organized according to the functional requirements
-documented in `roadmap.rst` in the `python_packaging` directory.
-
-## Usage
-
-For basic tests, install the Python package(s) (presumably into a virtualenv),
-then use the `pytest` executable to run these tests against the installed
-package(s).
-
-`pytest $LOCAL_REPO_DIR/python_packaging/test`
-
-where `$LOCAL_REPO_DIR` is the path to the local copy of the GROMACS source repository.
-
-For multi-process tests, run with an MPI execution wrapper and the `mpi4py` module.
-
-`mpiexec -n 2 python -m mpi4py -m pytest $LOCAL_REPO_DIR/python_packaging/test`
-
-## Controlling output
-
-Refer to pytest documentation for command line options to control the type and detail of output.
-Some high level overview and basic tasks are online at https://docs.pytest.org/en/3.9.3/usage.html
-but you should run `pytest -h` in a terminal to get the complete set of available options
-(in particular, note *log_cli* and *log_level*).