Refresh documentation site

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -19,6 +19,26 @@ body:
         - Other
     validations:
       required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: What operating system are you using?
+      multiple: true
+      options:
+        - Windows
+        - macOS
+        - Linux
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: What version of Gambit are you using?
+      description: Please provide the version number.
+      placeholder: e.g., 16.3.0
+      value: "16.3.0"
+    validations:
+      required: true
   - type: textarea
     id: what-happened
     attributes:

.github/workflows/lint.yml

@@ -2,7 +2,15 @@ name: Linters and coding standards checks
 
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
 
 jobs:
   clang-format:

.github/workflows/osxbinary.yml

@@ -2,6 +2,10 @@ name: MacOS static GUI binary
 
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
     tags:
       - 'v*'
   schedule:

.github/workflows/python.yml

@@ -2,7 +2,15 @@ name: pygambit Python extension
 
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
 
 jobs:
   linux:

.github/workflows/tools.yml

@@ -2,7 +2,15 @@ name: Build executables
 
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
 
 jobs:
   linux:

.github/workflows/wheels.yml

@@ -1,7 +1,12 @@
+
 name: pygambit wheels
 
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - 'README.md'
     tags:
       - 'v*'
   schedule:

.readthedocs.yml

@@ -8,7 +8,7 @@ formats: all
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.13"
   apt_packages:
     - libgmp-dev
 

README.md

@@ -13,6 +13,9 @@
 
 **Gambit** is the package for doing computation in (non-cooperative) game theory.
 
+- See our [documentation](https://gambitproject.readthedocs.io/)
+- Check our [project website](https://www.gambit-project.org/)
+
 Gambit provides:
 
 - Structures to represent games in extensive and strategic form

doc/Makefile

@@ -11,11 +11,12 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest livehtml
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
+	@echo "  livehtml  to make HTML files with auto-rebuild and live server"
 	@echo "  dirhtml   to make HTML files named index.html in directories"
 	@echo "  pickle    to make pickle files"
 	@echo "  json      to make JSON files"
@@ -34,6 +35,11 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 
+livehtml:
+	sphinx-autobuild -b html $(ALLSPHINXOPTS) _build/html --host 0.0.0.0 --port 8000
+	@echo
+	@echo "Live server started at http://localhost:8000"
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
 	@echo

doc/_templates/layout.html

@@ -12,10 +12,11 @@
 
 {% block relbar1 %}
 
-<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
-<a href="{{ pathto('index') }}"><img src="{{
-pathto("_static/gambit.png", 1) }}" border="0" alt="Chadwick"/></a>
-<font size="+3">Gambit: Software Tools for Game Theory</font>
+<div style="background-color: white; text-align: center; padding: 10px 10px 15px 15px; align-items: center;">
+    <a href="https://www.gambit-project.org/"><img src="{{
+    pathto("_static/gambit.png", 1) }}" border="0" alt="Chadwick" style="width: 12%;"/></a>
+
+    <h4 style="color: #cc0000; margin: 0 auto; text-align: center; width: 100%;">Software tools for game theory.</h3>
 </div>
 {{ super() }}
 {% endblock %}

doc/conf.py

@@ -28,6 +28,10 @@
     "sphinx_design",
 ]
 
+# IPython directive configuration
+ipython_execlines = ['import pygambit as gbt', 'import os', 'import sys']
+ipython_savefig_dir = 'savefig'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -100,7 +104,35 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "external_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/gambitproject/gambit"
+        },
+        {
+            "name": "Releases",
+            "url": "https://github.com/gambitproject/gambit/releases"
+        },
+        {
+            "name": "Older releases",
+            "url": "https://sourceforge.net/projects/gambit/files/"
+        },
+        {
+            "name": "Cite Gambit",
+            "url": "https://www.gambit-project.org/cite/"
+        }
+    ],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/gambitproject/gambit",
+            "icon": "fab fa-github-square",
+            "type": "fontawesome",
+        }
+    ],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

doc/contents.rst

@@ -7,11 +7,11 @@ Detailed table of contents
    :maxdepth: 3
 
    intro
-   tools
    pygambit
+   tools
    gui
    samples
-   build
+   developer
    formats
    biblio
 

doc/build.rst → doc/developer.build.rst

@@ -1,5 +1,5 @@
-For developers: Building Gambit from source
-===========================================
+Building Gambit from source
+===========================
 
 This section covers instructions for building Gambit from source.
 This is for those who are interested in developing Gambit, or who
@@ -144,34 +144,3 @@ using `nose2`.
 
 Once installed, simply ``import pygambit`` in your Python shell or
 script to get started.
-
-Editing this documentation
---------------------------
-
-1. If you haven't already, clone the Gambit repository from GitHub: ::
-
-    git clone https://github.com/gambitproject/gambit.git
-    cd gambit
-
-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: ::
-
-    python -m venv docenv
-    source docenv/bin/activate
-
-3. Install the requirements and make the docs: ::
-
-    pip install .
-    cd doc
-    pip install -r requirements.txt
-    make html
-
-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.
-
-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

doc/developer.contributing.rst

@@ -0,0 +1,87 @@
+Contributing to the Gambit Project
+==================================
+
+This section provides guidelines for contributing to the Gambit project, including how to report bugs, suggest features, and contribute code.
+It includes information relevant to both core developers and external contributors.
+
+GitHub issues
+----------------
+
+In the first instance, bug reports, feature requests and improvements to the Gambit documentation should be
+posted to the Gambit issue tracker, located at
+`<http://github.com/gambitproject/gambit/issues>`_.
+Use the issue templates to help you provide the necessary information.
+
+When reporting a bug, please be sure to include the following:
+
+* The version(s) of Gambit you are using.  (If possible, it is helpful
+  to know whether a bug exists in both the current stable/teaching and
+  the current development/research versions.)
+* The operating system(s) on which you encountered the bug.
+* A detailed list of steps to reproduce the bug.  Be sure to include a
+  sample game file or files if appropriate; it is often helpful to
+  simplify the game if possible.
+
+Contributing code
+----------------
+
+Gambit is an open-source project, and contributions are welcome from anyone.
+The project is hosted on GitHub, and contributions can be made via pull requests following the standard GitHub workflow.
+
+1. To get started contributing code in the `Gambit GitHub repo <https://github.com/gambitproject/gambit>`__, do one of the following:
+
+- Core developers: request contributor access from one of the `team <https://www.gambit-project.org/team/>`__
+- External contributors: fork the repository on GitHub.
+
+2. Clone the repository to your local machine ::
+
+    git clone https://github.com/gambitproject/gambit.git  # or your fork URL
+    cd gambit
+
+3. 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 ::
+
+    git add .
+    git commit -m "Add feature X or fix bug Y"
+
+5. 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.
+
+Editing this documentation
+--------------------------
+
+1. If you haven't already, clone the Gambit repository from GitHub: ::
+
+    git clone https://github.com/gambitproject/gambit.git
+    cd gambit
+
+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: ::
+
+    python -m venv docenv
+    source docenv/bin/activate
+
+3. Install the requirements and make 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.
+
+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
+

doc/developer.rst

@@ -0,0 +1,13 @@
+.. _developer:
+
+
+Developer docs
+==============
+
+This section contains information for developers who want to contribute to the Gambit project, including how to build Gambit from source, how to contribute code, and how to report bugs.
+
+.. toctree::
+   :maxdepth: 2
+
+   developer.build
+   developer.contributing

doc/gui.rst

@@ -1,8 +1,8 @@
 .. _section-gui:
 
-***********************
-The graphical interface
-***********************
+***
+GUI
+***
 
 Gambit's graphical user interface provides an
 "integrated development environment" to help visually construct