Documentation: front page and pages beyond the API reference

[rahulsavani]

@nataliemes @stengel now that the docstring PRs (#19, #20, #24) are merged, here are some suggestions for the next step: a proper front page and some pages beyond the API reference. Comments, disagreements and additions very welcome. Once we agree, we can turn the pages into issues.

Current state

The documentation at https://gambitproject.readthedocs.io/projects/lemke/en/latest/ is built from main by Read the Docs. It has two parts:

• a front page with a one-sentence description and an install command;
• an API reference generated from the docstrings (lemke.lemke, lemke.bimatrix, lemke.randomstart, lemke.utils, lemke.columnprint).

A newcomer gets no worked example, no description of the input file formats, no command-line usage and no explanation of the algorithms. The file formats are the biggest gap: at the moment you can only work them out by reading the from_file docstrings or the bare files in examples/.

A new front page (index.rst)

The front page should stay short and lead the reader somewhere. Suggested contents:

1. What it is and who it's for. A pure Python implementation using exact rational arithmetic, built for teaching and research, where you want to see each pivot. Mention the link to Gambit and to Bernhard von Stengel's work.

2. Feature bullets:

   • Lemke's algorithm for linear complementarity problems, with a covering vector d;
   • lexicographic handling of degenerate problems;
   • Lemke–Howson and the tracing procedure for bimatrix games;
   • verbose tableau output that shows every pivot;
   • command-line tools: lemke, bimatrix and randomstart.

3. A 30-second example in two parts:

   • solving a 2×2 LCP from Python, showing the result (z = (1/3, 1/3));
   • running bimatrix lh examples/game on the command line, with its output.

4. Installation. Say plainly that the package is not on PyPI and needs Python 3.10 or later. The install command is:

   pip install git+https://github.com/gambitproject/lemke.git
   

5. Links to the sections below. The pydata theme can show these as cards using sphinx-design, which would be a new docs dependency.

6. Author, how to cite, and licence (GPL-3.0).

New pages, in priority order

1. Getting started (tutorial)

• Solve an LCP from Python, then from a file.
• Read an LcpResult: success, z, w, and what ray termination means.
• Solve a bimatrix game, both in Python and on the command line.
• Use PrintingCallback to watch the pivots.

2. File formats (reference)

This is the most needed page. Getting these details right in the docstrings took two rounds of fixes, which shows how easy they are to get wrong. It should cover:

• LCP files: n=, then M= with the entries given row by row, then q= and d=.
• Game files: m n, then the entries of A, then the entries of B.
• Numbers: integers, fractions written as p/q, or decimals, and how the --decimals option rounds decimals.
• Comments: only whole lines starting with #, % or * are ignored. A # in the middle of a line does not start a comment.
• Annotated copies of the files in examples/.

3. Command-line reference

Generate it from the Click definitions with sphinx-click, so it can never drift from the code. Then add explanations by hand for things --help can't show:

• the --labels range syntax, e.g. 1,3-5,7-;
• how to read the output: the tableau, the basis= / z= / w= lines, "supports" and "found by labels".

4. Background and theory

@stengel is the natural author for this page. Suggested topics:

• the LCP, and complementary pivoting with the extra variable z0 and covering vector d;
• the lexicographic minimum-ratio test for degenerate problems;
• how a bimatrix game becomes an LCP (what createLCP builds);
• Lemke–Howson labels, and the tracing procedure from a prior;
• references to the literature.

Sphinx's built-in mathjax extension handles the mathematics.

5. Worked examples

• A degenerate LCP, and one that ends in ray termination.
• The coordination game in examples/game. This makes a good teaching point: bimatrix lh finds only the two pure equilibria and misses the mixed one, x = (7/9, 2/9), y = (2/5, 3/5).
• A randomstart plot, with the image generated when the docs are built.

6. Extensive-form games via the sequence form

tests/sequence_form_helper.py already builds sequence-form LCPs from Gambit games. That is a strong use case, but at the moment it exists only as test code. We need to decide whether to move it into the package before documenting it.

7. Contributing

• Development install: pip install -e ".[test,dev,doc]". The -e (editable) matters: with a normal install, the tests run against an old copy of the code instead of src/.
• pre-commit, running the tests, and building the docs locally with sphinx-autobuild.
• The PR workflow: when merging main into a branch, check git diff main...HEAD afterwards to make sure the merge didn't undo changes from main.

Configuration and housekeeping

• Run the docstring examples as tests in CI, using pytest --doctest-modules or sphinx.ext.doctest. Broken examples turned up in both docstring PRs (Add docstrings to lemke.py and bimatrix.py #19 and Add docstrings to randomstart.py #20). The examples that read "lcp.txt" or "game.txt" would need small fixture files.
• Add intersphinx so that types such as fractions.Fraction and numpy.ndarray link to the Python and NumPy documentation.
• Turn off undoc-members in conf.py. At the moment every internal helper appears in the API reference.
• Set version and release in conf.py from the package metadata.
• README: link to the live documentation and add a Read the Docs badge.
• Two small errors:
  • In examples/game, the comment # max= 4 for B is wrong: B's largest entry is 7.
  • The --decimals help text of the lemke command says "payoff digits", but an LCP has no payoffs.

Suggested order of work

1. The front page, Getting started and File formats give the most benefit soonest. @nataliemes could own these as a first docs PR, since they build on her docstring work.
2. The command-line reference via sphinx-click is mostly mechanical.
3. Background and theory is best written by Bernhard.
4. Worked examples, the sequence-form page and Contributing can follow.