Audit and review the project: go / no-go before further work

[mmcky]

This repository was built in a single session on 24 February 2026 and has not been touched since. Before anyone invests further, it deserves a deliberate audit — both of the code and of whether the project should continue at all.

Where things stand

Created	2026-02-24 03:16Z
Commits	15, all authored 01:55–03:13 on 2026-02-24, single author
Branches	main only
Tags / releases	none
PRs / issues before this batch	none
Downstream users	none — the one evaluation, QuantEcon/lecture-python-programming#475, was closed unmerged
Docs	https://quantecon.github.io/quantecon-sphinx-theme/, deployed once

The entire history was authored locally and pushed in one shot, then evaluated within the hour. Nothing has exercised it since. The known defects are tracked separately: #1 (inline math), #2 (RHS ToC), #3 (border), #4 (author/translator attribution), and #5 (positioning and name).

Scope of the audit

Strategic — answer first, since it gates the rest. Is this project still wanted? The two conflicting purposes on record (brand-neutral upstream base per PLAN.md, versus a second QuantEcon theme for non-core series per the evaluation PR) need reconciling, and the naming question depends on the answer. There is also a timing question: the QuantEcon lecture repos are migrating to Jupyter Book 2 / the MyST CLI, which changes the theming story substantially — a Sphinx theme targeting Jupyter Book ≥ 1.0, as PLAN.md specifies, may be aiming at a target that is moving out from under it. Worth confirming before writing more SCSS.

Technical, if it continues. Review the SCSS and JS structure against what quantecon-book-theme learned; check the pydata-sphinx-theme inheritance and how much is override-by-suppression (see 1a0ea07, which suppresses a duplicate pydata footer) versus genuine extension; verify accessibility claims in PLAN.md (WCAG 2.1 AA contrast, keyboard nav, reduced-motion) actually hold, since none appear to have been tested; assess docs/kitchen-sink.md coverage against real lecture content, which is what surfaced the math and ToC defects; and establish whether there is any test or visual-regression story at all.

Process, if it continues. Decide on a release process and cut a tagged version — the evaluation had to pin @ git+...@main, which is not reproducible and made it impossible to tell a stale build from a live defect. Also settle the Phase 2 scope in PLAN.md and whether the quantecon-book-theme inheritance goal is real or aspirational.

Outcome sought. A go / no-go, and if go, a short prioritised plan. If no-go, archive the repository so it does not sit in an ambiguous state — the work is recoverable from history either way.

[mmcky]

Outcome, 2026-09-04: hold — not go, not yet no-go

Reviewed as part of the theme-estate audit on QuantEcon/workspace-themes#1.

The decision. The repository stays open, with no further investment, and is recorded as an archive candidate with a named trigger: the move of the estate to mystmd backends. It is not being carried because the Sphinx positioning case got stronger — it did not — but because the design thinking in it has value for QuantEcon's community-focused themes, and that value is worth keeping legible until there is a mystmd home to carry it into.

This is deliberately not the fourth option of deferring again. The trigger is named, so the question does not have to be re-litigated from scratch: when the estate's Sphinx sites are off Sphinx, this is archived unless someone makes a positive case in the meantime.

The evidence the decision was taken on

History	15 commits, all on 2026-02-24 between 12:55 and 14:13 AEDT — one 78-minute session, single author
Since	main untouched for 192 days
Releases	none; no PyPI package (pypi.org/pypi/quantecon-sphinx-theme/json returns 404)
Tests	no tests/ directory; the tests session in noxfile.py:49 is a sphinx-build docs-compatibility build, not a test suite
CI	two runs ever — the 2026-02-24 push and a Copilot review on 2026-08-03
Uptake	0 stars, 0 forks, no dependants; the one evaluation, QuantEcon/lecture-python-programming#475, closed unmerged
Open defects	#1 inline $…$ maths, #2 RHS ToC, #3 border, #4 attribution

Both positioning options on record are weak, which is why neither was taken.

PLAN.md:26 states purpose 4 as serving as the upstream base that quantecon-book-theme can later inherit from. That theme already inherits pydata_sphinx_theme directly (theme.conf:2, pinned pydata-sphinx-theme>=0.15), so adopting the role means re-parenting a production theme — 63 open issues, roughly 100–500 PyPI downloads a day, seven external dependants — onto an untested codebase with no release process.

The other role on record, a second QuantEcon theme for non-core series, is the topics theme in the estate plan, and QuantEcon/workspace-themes#2 makes that a mystmd theme.

The timing objection this issue raises against itself also stands: a Sphinx theme targeting Jupyter Book ≥ 1.0 is aiming at a target the estate is moving off.

What follows from the hold

• No new SCSS, no defect fixes. Inline $...$ math does not render correctly #1, RHS table of contents is misaligned and hard to navigate #2, UI element has a broken lower border #3 and No support for Authors and Translator attribution per lecture #4 stay open as a record of what is wrong, not as a work list. Nobody should pick them up under this outcome.
• Documentation stays honest. Correct the install instructions and state the project's status #7 is merged, so the README carries an in-development banner and a pinned git install, and docs/index.md and docs/getting-started.md no longer tell readers to install a package that does not exist. That is the correct state to hold the repository in, and the correct state to archive it in later.
• Decide the theme's positioning, then its name #5, positioning and name, stays open and is answered by the same trigger. If the outcome is archive, the name is freed and QuantEcon/workspace-themes#2 may want it.
• Before archiving, harvest PLAN.md. The design thinking is the asset being preserved here. When the trigger fires, that content should be carried into whatever mystmd community-theme work exists rather than left to the repository's history.

Review trigger

Revisit when the estate's Sphinx sites move to mystmd backends — in tracker terms, when the parity gate QuantEcon/quantecon-theme.mystmd#147 closes and the lecture cutover is under way. Until then this issue stays open and nothing else here does.