QuantEcon / QuantEcon/QuantEcon.py

MAINT: Refresh the docs toolchain: unpin Sphinx, drop vendored sphinxext, deduplicate floors

Open
#885 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

maintenance
Dominant language
Python
Stars
2.4k
Forks
2.3k
Avg merge
3d 3h
Merged PRs (30d)
3

Description

Problem
  • docs/rtd-requirements.txt pins sphinx<=6.2.1 (April 2023; Sphinx is on 8.x) while the RTD image is otherwise current — an increasingly tight constraint on theme/extension versions and a latent docs-build failure.
  • The same file re-declares runtime floors (numba>=0.49, numpy>=1.17, scipy>=1.5) — a second copy of metadata the install-metadata issue in this milestone is changing; it will drift (and already has).
  • docs/sphinxext/ vendors three ~2014 IPython/matplotlib extensions (ipython_directive.py, ipython_console_highlighting.py, only_directives.py). conf.py puts the directory on sys.path but its extensions list loads IPython.sphinxext.* — the maintained upstream versions — so the vendored copies are pure dead weight.
Proposed change
  1. Delete docs/sphinxext/ and the sys.path.insert for it in conf.py; confirm the IPython-shipped directives cover current usage.
  2. Unpin Sphinx (or float a modern floor, sphinx>=8); rebuild on RTD; fix whatever surfaces (typically theme/config deprecations).
  3. Collapse the duplicated runtime floors: the RTD config already pip-installs the package, so rtd-requirements.txt should hold docs-only tools (sphinx, theme, numpydoc, ipython, matplotlib).

Content/generator work (#854, #852, #169) is out of scope — this is the toolchain under it.

Acceptance criteria
  • Clean RTD build on current Sphinx; no docs/sphinxext/; zero new build warnings (or enumerated and issue-linked)
  • Runtime dependency versions stated in exactly one file (pyproject.toml)

From the July 2026 technical-debt audit (AI-assisted; claims verified against 28d4b3b on 2026-07-25).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/rtd-requirements.txt and conf.py, then inspect the RTD configuration and pyproject.toml to compare dependency floors. Rebuild the documentation on current Sphinx and use the resulting warnings or deprecations to guide the required configuration fixes. Done means no docs/sphinxext/, runtime floors only in pyproject.toml, and a clean build or documented warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
matplotlib, numpy, python
Domain
build-system, documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.