diff --git a/.github/ISSUE_TEMPLATE/tutorial_request.yml b/.github/ISSUE_TEMPLATE/tutorial_request.yml new file mode 100644 index 000000000..00d0ed34a --- /dev/null +++ b/.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: "" diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index 96d66953f..ed490af7f 100644 --- a/doc/developer.contributing.rst +++ b/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 `__ 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 diff --git a/doc/tutorials/running_locally.rst b/doc/tutorials/running_locally.rst index 075511cec..756ae7056 100644 --- a/doc/tutorials/running_locally.rst +++ b/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 diff --git a/tests/test_tutorials.py b/tests/test_tutorials.py index 6724235dd..c4d481b12 100644 --- a/tests/test_tutorials.py +++ b/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