Add GH issue tutorial request template and tutorial submission guide (#622)

* Adds a GitHub issue template to suggest/request a tutorial
* Adds a ew section in documentation on how to contribute a tutorial
* Improves test suite's collection of tutorial notebooks

Author: edwardchalstrey1

.github/ISSUE_TEMPLATE/tutorial_request.yml

@@ -0,0 +1,27 @@
+name: Tutorial request
+description: Submit a request for a new tutorial to be added to the Gambit documentation.
+title: "[Tutorial]: "
+labels: ["tutorial", "documentation"]
+body:
+  - type: textarea
+    id: describe
+    attributes:
+      label: Describe the tutorial you want to see.
+      description: Go into as much detail as you can regarding the tutorial you would like to see, how long it should be etc.
+      value: "Add a tutorial demonstrating the core components of the PyGambit API."
+    validations:
+      required: true
+  - type: textarea
+    id: describe
+    attributes:
+      label: Who is the tutorial for?
+      description: Explain who the target audience is for this tutorial and what prior knowledge they should have.
+      value: "Newcomers to game theory and the Gambit software who have basic Python programming skills."
+    validations:
+      required: true
+  - type: textarea
+    id: links
+    attributes:
+      label: Add links to papers and software.
+      description: Add links to any research papers or other resources the author will need to write this tutorial.
+      value: ""

doc/developer.contributing.rst

@@ -109,7 +109,18 @@ You can also build the documentation locally to preview your changes before subm
 
 4. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
 
+Contributing tutorials
+^^^^^^^^^^^^^^^^^^^^^^
 
+To submit a tutorial for inclusion in the Gambit documentation, please follow these steps:
+
+1. Open a GitHub issue using the *Tutorial request* issue template on the `Gambit GitHub repo <https://github.com/gambitproject/gambit/issues/new/choose>`__ or choose an issue already opened with the `tutorial` label.
+
+2. Write the tutorial as a Jupyter notebook (`.ipynb` file), following the style and format of existing tutorials in the `doc/tutorials` directory. Develop this on a branch as per the instructions in :ref:`contributing-code`. Add the tutorial to the `doc/tutorials` directory in the repository. Put it in an appropriate subdirectory or create a new one if necessary.
+
+3. Update `doc/pygambit.rst` to ensure the tutorial is listed in the docs at an appropriate location.
+
+4. *[Optional]* If your tutorial requires additional dependencies not already listed in `doc/requirements.txt`, please add them to the file.
 
 
 Recognising contributions

doc/tutorials/running_locally.rst

@@ -9,14 +9,16 @@ You will need a working installation of Python 3.9+ on your machine to run PyGam
 1. To download the tutorials, open your OS's command prompt and clone the Gambit repository from GitHub, then navigate to the tutorials directory: ::
 
     git clone https://github.com/gambitproject/gambit.git
-    cd gambit/doc/tutorials
+    cd gambit/doc
 
-2. Install `PyGambit` and `JupyterLab`. We recommend creating a new virtual environment and installing both the requirements there. e.g. ::
+2. Install `pygambit` and other requirements (including `JupyterLab` and other packages used by the tutorials). We recommend creating a new virtual environment and installing both the requirements there. e.g. ::
 
     python -m venv pygambit-env
     source pygambit-env/bin/activate
-    pip install pygambit jupyterlab
+    pip install pygambit
+    pip install -r requirements.txt
 
 3. Open `JupyterLab` and click on any of the tutorial notebooks (files ending in `.ipynb`) ::
 
+    cd tutorials
     jupyter lab

tests/test_tutorials.py

@@ -16,17 +16,9 @@ def _find_tutorial_notebooks():
     if not root.exists():
         pytest.skip(f"Tutorials folder not found: {root}")
 
-    # Collect notebooks from the tutorials root (recursive).
-    notebooks = set(root.rglob("*.ipynb"))
+    # Collect all notebooks under doc/tutorials (including any subfolders).
+    notebooks = sorted(set(root.rglob("*.ipynb")))
 
-    # Also explicitly include notebooks under an "advanced_tutorials" subfolder
-    # (in case they are separate or not picked up for some layouts). Use a set
-    # to deduplicate if the subfolder is already part of the root search.
-    advanced = root / "advanced_tutorials"
-    if advanced.exists():
-        notebooks.update(advanced.rglob("*.ipynb"))
-
-    notebooks = sorted(notebooks)
     if not notebooks:
         pytest.skip(f"No tutorial notebooks found in: {root}")
     return notebooks