Requested documentation improvement

• From looking at the existing user guide before I thought that it would be clearer to separate each line in the included script into separate code snippets for clarity
  • Currently this is just an rst doc
• Jupyter notebook versions of the tutorials that can be run interactively locally or with a Colab/Binder button
  • Perhaps a very basic example could involve setting up prisoners dilemma, or adapt the existing one-shot poker
  • Should there be an example that uses new_table as well as new_tree function?
• Maybe this should be done after Collect information on Gambit userbase past and present alan-turing-institute/gambit_admin#5 to understand how useful this might be
• Rahul is also working on notebooks for some teaching materials

Related

• Does PyGambit have a way of visualising the game trees? Or can you only do that with the UI? If not, seems like a good issue to open - opened Add easy way to visualise game trees in PyGambit #552
• Ensure append_move and other functions to apply labels to nodes by default #553

[WIP] Proposed structure

Instead of the current user guide, several notebooks covering the following:

• 01 Quickstart notebook tutorial detailing basics of PyGambit API
  • Set up simplest normal form game (Prisoner's Dilemma) in clearest way using Game.new_table
  • Also with fewer lines of code using Game.from_arrays()
  • Game.to_arrays() which produces the players’ payoff tables given a strategic game
  • Demo computing of Nash equilibrium in one line of code
  • Second example, extensive form "One-shot trust game with binary actions" showing Game.new_tree
  • Save a game to a file (nfg)
  • Read a game from file
  • Update the parts where we set labels to explain that "you can reference nodes by indices, however setting labels aids the game setup code interpretability)
• 02 Extensive form tutorial
  • Trust game example
  • Save a game to a file (efg)
  • Read a game from file
• 02 One-card poker A complex game example walkthrough e.g. one-card poker with private information, but with explanations of all the script setup
  • Compute the Nash equilibria again, and copy in the explainer in the "Computing Nash equilibria" section, which uses the Poker example
  • "Acceptance criteria for Nash equilibria" section talks about some of the differences between methods, put it here
  • Representation of numerical data of a game
• 04 Starting points covering what's in the "Generating starting points for algorithms" section which sets up a different game (read from file) and demonstrates finding different equilibria when using different "starting points"
• 05 "Quantal response equilibrium" tutorial
• [Documentation]: Idea - tutorial demonstrating OpenSpiel & Gambit workflow #555

User guide should be refactored as a homepage with sections that can be either rst docs (below) or ipynb tutorials (as above):

• User guide intro/landing page
  • Contents - summarise what each page/tutorial covers
  • Clicking next should iterate through tutorials first, then the below
• Setup doc with Python instructions for running the notebooks locally but also says "click continue to view online rendered"
• The table of algorithms (in the API they all are called pygambit.nash.[algorithmX]_solve) should be moved under the API documentation header before the toc and explain that the links are to the equivalent CLI and PyGambit functions
• Lifetime of a game object and its elements
  • This section should be removed, it is just explaining what would be obvious to Python users, or rather it explains Python rather than PyGambit
• Using external programs
  • Explains that there are a couple of algorithms that need an external package to be installed to be used
  • Open a new issue to add tested install guides for both of these: [Documentation]: Improve guide for external Nash equilibria software used by Gambit #561

Testing

• Ensure the tutorials are rendered on the pages of sphinx docs but can also be downloaded by cloning Gambit
• Do a final pass of docs to ensure everything looks right and reads well
  • Re-run cells of all notebooks
• To note, the current user guide has associated tests that just run the same lines of code. Is there way to test the notebooks run to completion instead? - opened a new issue: Update PyGambit tests to run tutorial notebooks #562