QuantEcon / QuantEcon/QuantEcon.py
MAINT: Refresh the docs toolchain: unpin Sphinx, drop vendored sphinxext, deduplicate floors
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.4k
- Forks
- 2.3k
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 3
Description
Problem
docs/rtd-requirements.txtpinssphinx<=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.pyputs the directory onsys.pathbut itsextensionslist loadsIPython.sphinxext.*— the maintained upstream versions — so the vendored copies are pure dead weight.
Proposed change
- Delete
docs/sphinxext/and thesys.path.insertfor it inconf.py; confirm the IPython-shipped directives cover current usage. - Unpin Sphinx (or float a modern floor,
sphinx>=8); rebuild on RTD; fix whatever surfaces (typically theme/config deprecations). - Collapse the duplicated runtime floors: the RTD config already pip-installs the package, so
rtd-requirements.txtshould 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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