DOC: repo-wide documentation consistency audit

[mmcky]

Summary

A systematic audit of the documentation surface — Sphinx sources, the apidoc generator, every docstring in the package, the repo-level prose docs, build config, and every hyperlink — together with the fixes it turned up. One open question (#853) is deliberately left untouched.

Findings were verified against the code rather than taken at face value, and the resulting diff was reviewed again for regressions before this PR.

Highest-impact fixes

The published docs describe the wrong package. docs/source/conf.py put a cwd-relative path on sys.path. Sphinx runs from docs/, so it resolved to a directory that does not exist, and autodoc silently fell through to whatever quantecon happened to be installed in site-packages instead of the checkout. Read the Docs has therefore been publishing API docs generated from the installed wheel. The entry is now __file__-relative. Locally this changed the reported version in the built output from the installed 0.12.0 to the checkout's version.

quantecon.timings was documented nowhere. It is exported at top level and declares its own __all__, but grep -r timings docs/ returned zero hits. The generator now emits a Timings section, and the generated pages are committed.

A documented rebuild path was broken. qe_apidoc.py never created source/game_theory/game_generators/, so the make srcclean && python qe_apidoc.py sequence in docs/README.md crashed with FileNotFoundError. srcclean also silently skipped source/optimize, so a "clean" rebuild left stale pages.

Docstrings that contradict the code. robust_rule, robust_rule_simple and evaluate_F in _robustlq.py each documented a return order that does not match their return statement. nnash in _lqnash.py had the S1/S2 shapes swapped — the tests do not catch it because they use k_1 == k_2. Around 90 further parameter, return, default and type corrections follow, plus numpydoc structural fixes (a bare .. deprecated:: and a missing blank line before a list were both docutils errors, so those admonitions never rendered).

31 broken examples. A --doctest-modules sweep found examples showing output no supported NumPy produces (pre-1.14 array spacing), NumPy 2 scalar reprs, missing imports, and two outright NameErrors — including lorenz(), which does not exist. All 31 were fixed and each verified by running it. Examples that take a random_state now use the rng = np.random.default_rng(1234) pattern throughout, with every expected output regenerated by running the example.

Prose corrected against ground truth. The README source-install block (ran flit install with no cd, so it could not work), the BibTeX entry (carried the Zenodo DOI on a JOSS @article), and around ten dead or redirecting URLs — two of which, lectures.quantecon.org and discourse.quantecon.org, are NXDOMAIN.

Please look closely at these two

Both are behaviour changes rather than documentation, and both are reasonable to push back on:

Change	Why	Risk
requires-python: >=3.7 → >=3.12	Matches the classifiers, the CI matrix and RTD. Stale since the 2022 flit migration.	Narrows installability — users below 3.12 stop resolving new releases. Worth a line in the release notes.
Removed quantecon/util/common_messages.py	Referenced nowhere (grep hits only its own definition), and it describes a graceful Numba fallback that no longer exists, since numba is a hard dependency and __init__.py hard-raises.	It was importable, so this is an API removal.

Also included

Adds a docs job to CI. Nothing built the docs, which is precisely how the conf.py and srcclean breakage survived unnoticed. The job runs qe_apidoc.py and then git diff --exit-code -- docs/source, because RTD builds the committed .rst files and never runs the generator — regenerating without the drift check would pass green while RTD served stale pages. It builds without -W for now, since six warnings remain pending #853.

Unpins sphinx<=6.2.1, added in #708 as a temporary workaround for #707, now closed — the pin held the docs on a 2023 Sphinx whose metadata tops out at Python 3.11 while RTD builds on 3.14. Deletes the dead docs/sphinxext/ (three vendored modules, all commented out of conf.py) and MANIFEST.in (names a nonexistent LICENSE.txt, and flit never reads it). The 21 deprecation shims said "will be removed v0.8.0"; v0.8.0 shipped in February 2025, so the wording is now version-agnostic — an actual removal schedule is a separate discussion.

The Sphinx unpin and the sphinxext deletion are the first two items of #885 from the technical-debt audit. Its third item, moving the duplicated runtime floors out of rtd-requirements.txt, is not part of this PR, so #885 stays open for that.

Since the last review round (10 September 2026)

Merged main. Three files conflicted. .github/copilot-instructions.md was deleted upstream in #941 and AGENTS.md now carries that guidance (it makes none of the stale CI-matrix or test-count claims this branch had corrected), so the deletion stands. quantecon/random/utilities.py keeps the draw docstring from #917, which supersedes the seeded example discussed in the review thread — draw now takes an rng and its example uses the same generator pattern as the rest of the module. normal_form_game.py keeps the tol wording from #936.

The discrete_var example shows the simulated path again rather than its .shape. The output is deterministic under the seeded generator, and the same block already prints exact state_values from the same stream, so it introduces no new fragility.

The docs job now uses actions/setup-python@v7, matching the rest of ci.yml after Dependabot's bump on main.

The ci_np2.yml trigger fix that earlier versions of this description mentioned landed separately in #911 and is no longer part of this diff.

The index page's description of util now names only Timer and timeit as the user-facing timing tools, so it does not advertise tic/tac/toc ahead of their deprecation in #833. That PR merges cleanly onto this branch in either order.

For the release notes

Release notes are generated from PR titles at tag time, and this PR's title would hide the removals below. Whoever cuts the next release should carry these into the notes by hand:

• requires-python is now >=3.12. Users on older interpreters stop resolving new releases.
• quantecon.util.common_messages is removed. It held a single string for a Numba-fallback path that no longer exists, and nothing imported it.
• docs/sphinxext/ is removed. It held vendored, Python 2 era copies of the IPython Sphinx directives and numpydoc's only_directives; the docs build has used the extensions shipped with IPython and matplotlib for years, and nothing referenced the directory beyond two sys.path entries in conf.py.
• MANIFEST.in is removed. It named a nonexistent LICENSE.txt, and flit never read it.
• The docs build is no longer pinned to sphinx<=6.2.1.

Deliberately not addressed

The six autodoc warnings that remain are the open question in #853 and are untouched here. See #853 for new findings on it, including why emptying ce_util.__all__ is not a clean option.

Six game_theory docstrings call np.set_printoptions(precision=4) and never restore it. Harmless as rendered documentation, but under a package-wide doctest run it leaks into every module collected later. Left alone; tracked separately.

Validation

• pytest quantecon on the merged branch — 678 passed, 2 pre-existing warnings
• flake8 --select=F401,F405,E231 quantecon — clean
• sphinx-build — succeeds, 6 warnings, all of them Six objects in the deprecated shims' __all__ are missing from the top-level quantecon namespace #853
• Doctests per module in isolation — every module touched by this PR passes, except util/timing.py, whose elapsed-time values are illustrative by design, and util/notebooks.py, which needs the network. Neither is masked with # doctest: +SKIP, which would render visibly in the published docs.
• qe_apidoc.py is idempotent and regenerates the committed .rst byte-for-byte on the merged branch, so the CI drift gate passes.
• An AST comparison with docstrings stripped confirms no executable code changed anywhere in quantecon/, apart from the shim deprecation strings and the removed module.

🤖 Generated with Claude Code

[mmcky]

@oyamad I am working through my review of this so I have left this in draft for now. But it is looking like a good update.

[Copilot]

Pull request overview

This PR performs a repo-wide documentation consistency pass across Sphinx configuration, the apidoc generator, docstrings/doctest snippets, and repo prose docs, and also introduces a docs build job in CI to prevent future doc drift.

Changes:

• Fixes Sphinx configuration so autodoc imports the in-repo quantecon (not an installed wheel) and improves cross-references via intersphinx.
• Extends docs/qe_apidoc.py and committed .rst sources to include the quantecon.timings API, and fixes srcclean to fully remove generated sources.
• Adds a docs CI job to regenerate + drift-check committed .rst sources and build HTML docs.

Reviewed changes

Copilot reviewed 99 out of 99 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates badges, links, install notes, citation
quantecon/util/timing.py	Updates timeit docstring/examples (doctest risk)
quantecon/util/notebooks.py	Clarifies docstring parameters/examples
quantecon/util/common_messages.py	Removes unused module
quantecon/util/combinatorics.py	Fixes doctest imports
quantecon/util/array.py	Fixes deprecation directive + doc typos
quantecon/timings/timings.py	Adds timings precision examples/output
quantecon/tests/util.py	Updates reference URL
quantecon/tests/test_inequality.py	Updates reference URL
quantecon/robustlq.py	Updates deprecation shim wording
quantecon/rank_nullspace.py	Updates deprecation shim wording
quantecon/random/utilities.py	Fixes doctests + doc typos/clarifications
quantecon/random/init.py	Documents/export draw
quantecon/quadsums.py	Updates deprecation shim wording
quantecon/quad.py	Fixes doc typos and clarifies parameters/returns
quantecon/optimize/tests/test_linprog_simplex.py	Updates reference URL
quantecon/optimize/scalar_maximization.py	Clarifies parameter defaults/order
quantecon/optimize/nelder_mead.py	Improves docs + doctest stability
quantecon/optimize/linprog_simplex.py	Fixes doc inconsistencies (phase flags etc.)
quantecon/optimize/lcp_lemke.py	Stabilizes doctest output type
quantecon/matrix_eqn.py	Updates deprecation shim wording
quantecon/markov/utilities.py	Fixes doctest imports
quantecon/markov/random.py	Fixes doctest formatting/imports
quantecon/markov/gth_solve.py	Fixes doc typo (“jit-compiled”)
quantecon/markov/estimate.py	Docstring formatting + adds missing parameter docs
quantecon/markov/ddp.py	Clarifies max_iter semantics + adds method doc
quantecon/markov/core.py	Doc clarifications + adds missing Parameters section
quantecon/markov/approximation.py	Fixes parameter order text + doctest stability
quantecon/markov/_ddp_linprog_simplex.py	Fixes doc typos/shape docs
quantecon/lss.py	Updates deprecation shim wording
quantecon/lqnash.py	Updates deprecation shim wording
quantecon/lqcontrol.py	Updates deprecation shim wording
quantecon/lae.py	Updates deprecation shim wording
quantecon/kalman.py	Updates deprecation shim wording
quantecon/ivp.py	Updates deprecation shim wording
quantecon/inequality.py	Updates deprecation shim wording
quantecon/gridtools.py	Updates deprecation shim wording
quantecon/graph_tools.py	Updates deprecation shim wording
quantecon/game_theory/vertex_enumeration.py	Fixes doctest imports/output stability
quantecon/game_theory/support_enumeration.py	Fixes doctest imports
quantecon/game_theory/repeated_game.py	Corrects return/shape docs
quantecon/game_theory/random.py	Fixes “Returns” section header
quantecon/game_theory/pure_nash.py	Fixes tol doc + doctest import
quantecon/game_theory/polymatrix_game.py	Replaces placeholder docstring with full docs
quantecon/game_theory/normal_form_game.py	Fixes doctest imports/formatting + doc clarity
quantecon/game_theory/mclennan_tourky.py	Fixes doctest variable name + formatting
quantecon/game_theory/logitdyn.py	Fixes parameter/attribute docs
quantecon/game_theory/lemke_howson.py	Fixes doctest imports/output + adds return docs
quantecon/game_theory/game_generators/bimatrix_generators.py	Normalizes doctest array formatting/imports
quantecon/game_theory/game_converters.py	Adds missing Parameters/Returns blocks
quantecon/game_theory/fictplay.py	Fixes doc typos and type docs
quantecon/filter.py	Updates deprecation shim wording
quantecon/estspec.py	Updates deprecation shim wording
quantecon/ecdf.py	Updates deprecation shim wording
quantecon/dle.py	Updates deprecation shim wording
quantecon/distributions.py	Removes incorrect params + fixes return doc spacing
quantecon/discrete_rv.py	Updates deprecation shim wording
quantecon/compute_fp.py	Updates deprecation shim wording
quantecon/ce_util.py	Updates deprecation shim wording
quantecon/arma.py	Updates deprecation shim wording
quantecon/_robustlq.py	Fixes return-order docs + type correction
quantecon/_rank_nullspace.py	Fixes rank/nullspace definition text
quantecon/_quadsums.py	Docstring cleanup + correct reference
quantecon/_matrix_eqn.py	Docstring cleanup + default corrections
quantecon/_lss.py	Fixes param name + doc typos
quantecon/_lqnash.py	Fixes shape docs + typo
quantecon/_lqcontrol.py	Fixes incorrect matrix description
quantecon/_lae.py	Stabilizes doctest by checking shape
quantecon/_kalman.py	Fixes typo + adds missing Returns docs
quantecon/_ivp.py	Fixes class name refs + doc formatting
quantecon/_inequality.py	Fixes doctest to call correct function
quantecon/_gridtools.py	Fixes doctest imports/output stability + typos
quantecon/_graph_tools.py	Fixes typo (“these”)
quantecon/_filter.py	Fixes typo + wraps lines
quantecon/_dle.py	Normalizes parameter names/types in docs
quantecon/_compute_fp.py	Fixes docstring quoting typo
quantecon/_arma.py	Fixes typo + adds missing Returns docs
pyproject.toml	Raises requires-python to >=3.12
MANIFEST.in	Removes unused MANIFEST.in
docs/sphinxext/only_directives.py	Removes unused vendored extension
docs/sphinxext/ipython_directive.py	Removes unused vendored extension
docs/sphinxext/ipython_console_highlighting.py	Removes unused vendored extension
docs/source/util/common_messages.rst	Removes docs page for deleted module
docs/source/util.rst	Removes common_messages from toctree
docs/source/timings/timings.rst	Adds committed timings API page
docs/source/timings.rst	Adds timings section to docs
docs/source/setup.rst	Updates PyPI + Git docs links
docs/source/index.rst	Adds timings section + clarifies util content
docs/source/game_theory.rst	Title-case section heading
docs/source/contributing.rst	Replaces dead Discourse link with issue tracker
docs/source/conf.py	Fixes sys.path import root + intersphinx mappings
docs/rtd-requirements.txt	Unpins Sphinx version
docs/README.md	Updates doc build instructions
docs/qe_apidoc.py	Fixes generator dirs + adds timings section
docs/Makefile	Fixes srcclean to remove more generated sources
CHANGELOG.md	Fixes dates and removes dead link markup
.github/workflows/ci.yml	Adds docs build + docs/source drift gate
.github/workflows/ci_np2.yml	Fixes pull_request trigger branch
.github/copilot-instructions.md	Updates repo guidance to match CI/docs reality

Comments suppressed due to low confidence (1)

quantecon/util/timing.py:350

• This timeit(add_func, runs=2) example prints output but the docstring provides no expected output, so doctest will fail. Make the call silent (or add expected output with ellipsis).

[oyamad]

I found one issue to comment on while I was just browsing.

[coveralls]

coverage: 90.9% (+0.02%) from 90.884% — docs/consistency-audit into main

[mmcky]

@oyamad 5e26642 implements your suggestion. The actual values change due to the change in underlying algorithm being used (despite the seed changing). Is this what you had in mind?

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

pyproject.toml:25

• requires-python is raised to ">=3.12", which is a breaking distribution change for users still pinned to Python 3.7–3.11. Please ensure this is clearly called out in the next release notes (and/or whichever release process the project uses) so downstreams understand why resolution/install stopped working on older interpreters.

dynamic = ["description", "version"]
requires-python = ">=3.12"
dependencies = [

[mmcky]

@oyamad I think this is in relatively good shape now. Thanks for your comments -- they were really helpful. Any other pickups? Otherwise I think this is a big improvement.

[Copilot]

🔵 Needs a closer look

It spans 60+ files and includes two intentional behavior changes (an importable-module removal and a requires-python narrowing) plus a new CI drift gate, which merit final human review despite no concrete defects being found.

Review details

• Files reviewed: 97/97 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[mmcky]

Author review complete. Every docstring correction was re-verified against the code, each changed module's examples run as doctests in isolation, and the apidoc drift gate, Sphinx build and full test suite are green on the merged branch. The removals are listed under "For the release notes" in the description. Ready to merge from my side; the two behaviour changes flagged above are still open for a second maintainer's view.

[mmcky]

@oyamad I have done a detailed review this morning. I think this is now in a good state to merge so I will do so.