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. Opened as a draft: the diff is large, and 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.

Prose corrected against ground truth. The CI matrix (claimed 3.11–3.13, actually 3.12–3.14), the test count (claimed 536, actually 600), 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.

Fixes the unexpanded $default-branch starter-template token in ci_np2.yml, which meant that workflow's pull_request trigger never matched. 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.

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 — 600 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 — 83 of 85 modules clean. The two exceptions need the network and the wall clock respectively; they were left as-is rather than 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, so the new 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.562% (+0.02%) from 90.546% — 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?

[oyamad]

In my opinion, this is not a good convention. (We should not introduce doctest until #916 is implemented.)

[mmcky]

Fair, and agreed it shouldn't become the convention — documenting the plan here so the thread has it.

The real fix is #917 (implementing #916): draw gains support for a passed-in np.random.Generator, and this example gets rewritten there to the same rng = np.random.default_rng(1234) pattern the rest of the module moved to in this PR — at which point the np.random.seed line and the Notes block below it both disappear. The seed line is a stopgap: with the current signature it's the only way the example can show real, reproducible output rather than property checks.

On the parenthetical — agreed, and it's how the PRs are sequenced: #920 (the doctest CI job) is stacked behind this PR and queued behind #917, so this example will never be enforced as a doctest in its seeded form. Intended landing order: this PR → #917 → #920.

[oyamad]

I still wonder why we want to include this "antipattern" even if it is temporary. Right now draw does not offer an option to generate reproducible outputs (in my opinion np.random.seed(1234) is not a choice), so the example should be as such, I suppose?

[oyamad]

Do we encourage the users to use int()? (Is np.int64(0) something we want to avoid?)

[mmcky]

I agree. I think an object repr is OK here.

[mmcky]

Good suggestion — adopted as the PR-wide convention in a99927a. This was one of four sites wrapping scalar outputs, so all four now show the object repr: np.int64(2) (cartesian_nearest_index), np.uint64(7) (_ints_arr_to_bits), np.float64(0.0) (lcp_lemke), and np.int64(0) here — each output verified by running the example. It's honest about what the functions actually return, and with CI and the docs build on NumPy 2 there's no portability cost. #917 will carry the same convention into the rewritten draw example.

[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.