QuantEcon / QuantEcon.py / 34417567059

94%

push

github

DOC: repo-wide documentation consistency audit (#864)

* DOC: repo-wide documentation consistency audit

Systematic audit of the documentation surface (Sphinx sources, the apidoc
generator, package docstrings, repo prose, build config and hyperlinks),
plus the fixes it turned up.

Docs build
- conf.py put a cwd-relative path on sys.path. Sphinx runs from docs/, so it
  resolved to a nonexistent directory and autodoc fell through to whatever
  quantecon was installed in site-packages rather than the checkout. Read the
  Docs has therefore been publishing docs built from the installed wheel. Now
  __file__-relative.
- html_static_path = [''] copied the whole confdir (72 .rst files + conf.py)
  into the published _static/. Now [].
- Added numpy/scipy to intersphinx_mapping.

Generator
- qe_apidoc.py never created source/game_theory/game_generators/, so the
  documented `make srcclean && python qe_apidoc.py` rebuild crashed with
  FileNotFoundError; srcclean also skipped source/optimize.
- quantecon.timings is a top-level export that was documented nowhere. It now
  gets a generated section.

Docstrings
- robust_rule, robust_rule_simple and evaluate_F in _robustlq.py documented
  return orders that contradict their return statements.
- nnash in _lqnash.py had the S1/S2 shapes swapped; the tests miss it because
  they use k_1 == k_2.
- ~90 further parameter/return/default/type corrections, numpydoc structural
  fixes, and typo corrections across the package.

Examples
- A --doctest-modules sweep found 31 broken examples (stale pre-NumPy-1.14
  array spacing, NumPy 2 scalar reprs, missing imports, and two NameErrors).
  All 31 fixed and verified by execution. Per module in isolation, 83 of 85
  modules are now doctest-clean; the two exceptions need the network and the
  wall clock, and were left untouched rather than masked with doctest
  directives.

Prose and metadata
- CI matrix (was 3.11-3.13, actually 3.12-3.14), test count (was 536, actually
  600), t... (continued)

0 of 12 new or added lines in 12 files covered. (0.0%)

5304 of 5835 relevant lines covered (90.9%)

0.91 hits per line