Refresh PyGambit user guide and add interactive Jupyter notebook option (#556)

* add new logo

* add headers and link

* Add livehtml target to Makefile and update build instructions for live server when doing local development to docs

* tidy navbar

* downgrade Ipython to support current docs build process and add matplotlib

* simplify docs landing page

* Add external links and icon links to the HTML theme configuration

* Update PyGambit documentation for clarity and installation instructions

* reorder so pygambit first

* add link to older releases

* remove download section

* move bug reports section

* Update developer section to clarify team contributions and provide a link to the team page

* pygambit before tools

* refactor history section to the bottom

* remove empty quickstart doc

* add links to docs and site on README

* developer docs section

* update toc with developer section

* add version number to bug report template

* add operating system dropdown to bug report template

* move issues section to top

* add contributing code guidelines to documentation

* update requirements.txt to specify package versions

* ignore 'doc/**' and '.github/ISSUE_TEMPLATE/**' paths in all workflows

* also dont run on README.md changes

* Update Python version to 3.11 in Read the Docs configuration

* add revised logo

* neat centred logo and title

* update ipython and jupyter

* restore old logo

* initial notebook

* better game setup

* calculate equilibria

* use player names and strategy names instead of indices

* explain strategy profiles and payoffs

* tidy

* add how to create a game from arrays

* add extensive form example start text

* add trust game existing content

* explicit API calls

* finish equilibrium explanation with TODO questions

* rename notebook

* initial poker setup with information sets

* add outcomes and assign to nodes

* explain the outcomes better

* rename

* move trust game into new notebook

* read and save games

* explain extensive and normal form game distinction

* demo saving efg

* add to_arrays

* explain labels

* remove todos

* full notebook content

* remove equilibrium computation from this example

* reference links

* some notes added to the part before computing equlibria

* better explanation

* better explanation

* explain better

* explain better

* explain belief

* explain realiz_prob and node_value

* rename var

* explain strategy payoff better

* explain difference between strategy and behaviour profiles

* explain strategy and profile classes and subclasses better

* compare both methods

* intro for Acceptance criteria for Nash equilibria section

* commit before stash

* maxregret

* end of poker example

* add section links

* clarify section header

* add starting points notebook

* tutorial assumptions

* tutorials purpose

* tutorial 4

* add qre notebook

* add links

* finish t05

* render tutorials

* add pandoc to readthedocs config

* add pandoc to documentation requirements

* fix typos and improve clarity in contributing documentation

* tidy notebooks and add subheader

* update tutorial section titles

* fix headers

* separate docs sections

* move tutorials onto pygambit homepage

* update homepage link to pygambit

* reduce user guide to remaining content not in tutorials

* add header and link to it for representation of numerical data of a game

* move numerical data representation in pygambit to tutorial 03

* restructure to remove original user guide completely

* reorder table and add explanation

* remove deprecated user guide link

* save the new table

* update tutorial explainers

* correct no of tutorials

* fix up algorithm table

* break up the PyGambit page appropriately

* refine tutorial titles and sections

* refactor developer doc

* update running_locally tutorial with detailed setup instructions

* update tutorial names

* take prisoners dilemma out of summary details tags

* move import

* final save t01

* use reference not link

* rerun cells

* tidy top markdown

* explain better

* typo

* explain better

* typo

* indent episilon equilibria text

* rerun notebook cells

* tidy t4 and t5

* resave nb outputs

* use prior_action.label as node labels

* use Node.prior_action.label to set node labels

* initial tests

* remove old userguide tests

* organise imports

* refactor: simplify kernel shutdown handling in notebook tests

* organise imports again

* fix: update dependencies in CI workflow to include nbformat, nbclient, and ipykernel

* style: fix indentation in docstrings for tutorial notebook tests

* fix: skip notebook test on Python 3.9 in CI

* just "games"

* move how to run up

* split tutorials on main page

* move advanced tutorials to their own folder

* refer to tutorials properly

* move external programs doc which currently isnt linked to anywhere and add todo

* fix link to advanced tutorials

* add text above advanced tutorials list

* refactor: enhance tutorial notebook discovery to include advanced tutorials

* fix link to nfg file

* Add *.so files to .gitignore

* remove tutorial games from git

* fix tutorial game paths

* comment out the save/load lines

* update tutorials to use action labels

* remove note

* use prior action labels for parent nodes too

* update test requirements.txt to include notebook dependencies

Author: edwardchalstrey1

.github/workflows/python.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install setuptools build cython pytest pytest-skip-slow wheel lxml numpy scipy
+          pip install setuptools build cython pytest pytest-skip-slow wheel lxml numpy scipy nbformat nbclient ipykernel
       - name: Build source distribution
         run:
           python -m build
@@ -38,7 +38,13 @@ jobs:
           cd dist
           pip install -v pygambit*.tar.gz
       - name: Run tests
-        run: pytest
+        run: |
+          if [ "${{ matrix.python-version }}" = "3.9" ]; then
+            # Python 3.9 on linux skips the notebook execution test (notebooks may require newer kernels/deps)
+            pytest -q -k 'not test_execute_notebook'
+          else
+            pytest
+          fi
 
   macos-13:
     runs-on: macos-13
@@ -56,7 +62,7 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install cython pytest pytest-skip-slow wheel lxml numpy scipy
+          pip install cython pytest pytest-skip-slow wheel lxml numpy scipy nbformat nbclient ipykernel
       - name: Build extension
         run: |
           python -m pip install -v .
@@ -79,7 +85,7 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install cython pytest pytest-skip-slow wheel lxml numpy scipy
+          pip install cython pytest pytest-skip-slow wheel lxml numpy scipy nbformat nbclient ipykernel
       - name: Build extension
         run: |
           python -m pip install -v .
@@ -102,7 +108,7 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install cython pytest pytest-skip-slow wheel lxml numpy scipy
+          pip install cython pytest pytest-skip-slow wheel lxml numpy scipy nbformat nbclient ipykernel
       - name: Build extension
         run: |
           python -m pip install -v .

.gitignore

@@ -38,4 +38,7 @@ gambit
 dist
 .venv
 *.dmg
-Gambit.app/*
+Gambit.app/*
+*.so
+doc/tutorials/games/*.nfg
+doc/tutorials/games/*.efg

.readthedocs.yml

@@ -11,6 +11,7 @@ build:
     python: "3.13"
   apt_packages:
     - libgmp-dev
+    - pandoc
 
 python:
   install:

doc/conf.py

@@ -26,6 +26,7 @@
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
     "sphinx_design",
+    "nbsphinx",
 ]
 
 # IPython directive configuration

doc/developer.contributing.rst

@@ -96,20 +96,21 @@ You can make changes to the documentation by editing the `.rst` files in the ``d
 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.
 
-1. Install the docs dependencies (into the virtual environment where you installed PyGambit): ::
+1. `Install Pandoc <https://pandoc.org/installing.html>`_ for your OS
+
+2. Install the docs dependencies (into the virtual environment where you installed PyGambit): ::
 
     pip install -r doc/requirements.txt
 
-2. Navigate to the Gambit repo and build the docs: ::
+3. Navigate to the Gambit repo and build the docs: ::
 
     cd doc
     make html  # or make livehtml for live server with auto-rebuild
 
-3. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
+4. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
+
 
 
-.. TODO: Add instructions for the GitHub workflow during contributor docs refactoring.
-   See https://github.com/gambitproject/gambit/issues/541
 
 Recognising contributions
 -------------------------
@@ -122,4 +123,4 @@ To add a contributor, comment on a GitHub Issue or Pull Request, asking @all-con
 
  @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.
+Refer to the `emoji key <https://allcontributors.org/docs/en/emoji-key>`__ for a list of contribution types.

doc/pygambit.rst

@@ -6,8 +6,68 @@ PyGambit
 
 See installation instructions in the :ref:`install` section.
 
+
+For newcomers to Gambit, we recommend reading through the PyGambit tutorials, which demonstrate the API's key capabilities for analyzing and solving games.
+These tutorials are available to be run interactively as Jupyter notebooks, see :ref:`local_tutorials`.
+All of the tutorials assume a basic knowledge of programming in Python.
+
+New user tutorials
+------------------
+
+These tutorials assume no prior knowledge of Game Theory or the PyGambit API and provide detailed explanations of the concepts and code.
+They are numbered in the order they should be read.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/running_locally
+   tutorials/01_quickstart
+   tutorials/02_extensive_form
+   tutorials/03_poker
+
+Advanced user tutorials
+-----------------------
+
+These tutorials assume some familiarity with the PyGambit API and Game Theory terminology and concepts including:
+
+- Nash equilibria
+- Pure and mixed strategies
+- Simplex representations of available strategies
+- Logit quantal response equilibrium (LQRE) correspondence
+
+Advanced tutorials:
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/advanced_tutorials/starting_points
+   tutorials/advanced_tutorials/quantal_response
+   .. pygambit.external_programs
+
+Algorithms for computing Nash equilibria
+----------------------------------------
+
+Interfaces to algorithms for computing Nash equilibria are provided in :py:mod:`pygambit.nash`.
+The table below summarizes the available PyGambit functions and the corresponding Gambit CLI commands.
+
+==========================================    ========================================
+CLI command                                   PyGambit function
+==========================================    ========================================
+:ref:`gambit-enumpure <gambit-enumpure>`      :py:func:`pygambit.nash.enumpure_solve`
+:ref:`gambit-enummixed <gambit-enummixed>`    :py:func:`pygambit.nash.enummixed_solve`
+:ref:`gambit-lp <gambit-lp>`                  :py:func:`pygambit.nash.lp_solve`
+:ref:`gambit-lcp <gambit-lcp>`                :py:func:`pygambit.nash.lcp_solve`
+:ref:`gambit-liap <gambit-liap>`              :py:func:`pygambit.nash.liap_solve`
+:ref:`gambit-logit <gambit-logit>`            :py:func:`pygambit.nash.logit_solve`
+:ref:`gambit-simpdiv <gambit-simpdiv>`        :py:func:`pygambit.nash.simpdiv_solve`
+:ref:`gambit-ipa <gambit-ipa>`                :py:func:`pygambit.nash.ipa_solve`
+:ref:`gambit-gnm <gambit-gnm>`                :py:func:`pygambit.nash.gnm_solve`
+==========================================    ========================================
+
+API documentation
+----------------
+
 .. toctree::
    :maxdepth: 2
 
-   pygambit.user
-   pygambit.api
+   pygambit.api