Refresh PyGambit user guide and add interactive Jupyter notebook option

.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