Update docs with how to run tests & add new tests (#598)

* add pytest instructions to contributing guide

* Update contributing guidelines to link to setup instructions for building Gambit from source

* simplify docs editing process

* increase subheader levels

* add note on adding new tests

* add section to recognize contributions and guide on using All Contributors

Author: edwardchalstrey1

doc/developer.build.rst

@@ -181,15 +181,15 @@ Building the Python extension
 
 The :ref:`pygambit Python package <pygambit>` is in ``src/pygambit``
 in the Gambit source tree. We recommend to install `pygambit`
-as part of a virtual environment rather than in the system's Python.
-Use `pip` to install from the **root directory of the source tree**, optionally including the `-e` flag for an editable install:
+as part of a virtual environment rather than in the system's Python (for example using `venv`).
+Use `pip` to install from the **root directory of the source tree**:
 
 .. code-block:: bash
 
+   python -m venv venv
+   source venv/bin/activate
    python -m pip install .
 
-There is a set of test cases in `src/pygambit/tests`, which can be run
-using `pytest`.
 
 Once installed, simply ``import pygambit`` in your Python shell or
 script to get started.

doc/developer.contributing.rst

@@ -45,50 +45,81 @@ version.
     git clone https://github.com/gambitproject/gambit.git  # or your fork URL
     cd gambit
 
-3. Create a new branch for your changes ::
+3. Follow the instructions in the :ref:`building-from-source` page to set up your development environment and build Gambit from source. If you only plan to make changes to the PyGambit Python code, you can skip to :ref:`build-python`.
+
+4. Create a new branch for your changes ::
 
     git checkout -b feature/your-feature-name
 
-4. Make your changes. Commit each change with a clear commit message ::
+5. Make your changes. Commit each change with a clear commit message ::
 
     git add .
     git commit -m "Add feature X or fix bug Y"
 
-5. Push your changes to your fork or branch ::
+6. Push your changes to your fork or branch ::
 
     git push origin feature/your-feature-name
 
-6. Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues.
-7. Core developers will review your changes, provide feedback, and merge them into the master branch if they meet the project's standards.
+7. Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues.
+8. Core developers will review your changes, provide feedback, and merge them into the master branch if they meet the project's standards.
+
+Testing your changes
+--------------------
+
+Be sure to familiarise yourself with :ref:`contributing-code` before reading this section.
+
+By default, pull requests on GitHub will trigger the running of Gambit's test suite using GitHub Actions.
+You can also run the tests locally before submitting your pull request, using `pytest`.
+
+1. Install the test dependencies (into the virtual environment where you installed PyGambit): ::
+
+    pip install -r tests/requirements.txt
+
+2. Navigate to the Gambit repository and run the tests: ::
+
+    pytest
+
+Adding to the test suite
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tests can be added to the test suite by creating new test files in the ``tests`` directory.
+Tests should be written using the `pytest` framework.
+Refer to existing test files for examples of how to write tests or see the `pytest documentation <https://docs.pytest.org/en/stable/>`_ for more information.
+
 
 Editing this documentation
---------------------------
+---------------------------
 
-1. If you haven't already, clone the Gambit repository from GitHub: ::
+Be sure to familiarise yourself with :ref:`contributing-code` before reading this section.
 
-    git clone https://github.com/gambitproject/gambit.git
-    cd gambit
+You can make changes to the documentation by editing the `.rst` files in the ``doc`` directory.
+Creating a pull request with your changes will automatically trigger a build of the documentation via the ReadTheDocs service, which can be viewed online.
+You can also build the documentation locally to preview your changes before submitting a pull request.
 
-2. Either install the docs requirements into your existing PyGambit development environment, or create a new virtual environment and install both the requirements and PyGambit there. For example, you can use `venv` to create a new environment: ::
+1. Install the docs dependencies (into the virtual environment where you installed PyGambit): ::
 
-    python -m venv docenv
-    source docenv/bin/activate
+    pip install -r doc/requirements.txt
 
-3. Install the requirements and make the docs: ::
+2. Navigate to the Gambit repo and build the docs: ::
 
-    pip install .
     cd doc
-    pip install -r requirements.txt
     make html  # or make livehtml for live server with auto-rebuild
 
-4. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
-
-5. Make any changes you want to the `.rst` files in the ``doc`` directory and rebuld the documentation to check your changes.
+3. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
 
-6. Follow the usual GitHub workflow to commit your changes and push them to the repository.
-
-7. Core developers will review your changes and merge to the master branch, which automatically deploys the documentation via the ReadTheDocs service.
 
 .. TODO: Add instructions for the GitHub workflow during contributor docs refactoring.
    See https://github.com/gambitproject/gambit/issues/541
 
+Recognising contributions
+-------------------------
+
+Gambit is set up with `All Contributors <https://allcontributors.org/>`__ to recognise all types of contributions, including code, documentation, bug reports, and more.
+
+You can see the list of contributors on the README page of the `Gambit GitHub repo <https://github.com/gambitproject/gambit>`__.
+
+To add a contributor, comment on a GitHub Issue or Pull Request, asking @all-contributors to add a contributor:
+
+ @all-contributors please add @<username> for <contributions>
+
+Refer to the `emoji key <https://allcontributors.org/docs/en/emoji-key>`__ for a list of contribution types.

tests/requirements.txt

@@ -0,0 +1 @@
+pytest==9.0.0