Restore per-document bibliography sections

[drbenvincent]

Background

In #834 (commit 3694557, "docs: consolidate bibliography into a single global references page") we replaced ~22 per-notebook :::{bibliography}::: blocks with a single global docs/source/references.rst. The change was forced by an upstream limitation in sphinxcontrib-bibtex: per-document bibliographies produced bibtex.duplicate_citation warnings for every shared key and, more critically, the rendered citation hyperlinks resolved non-deterministically — a {cite:t} on page A could silently link to page B's bibliography. The trade-off was readers leaving the page they were on to see a reference, which is a meaningful UX regression for an educational docs site.

We filed mcmtroffaes/sphinxcontrib-bibtex#385 describing the problem and proposing a same-document-preferred resolution. The maintainer addressed it in PR #387, slated for the 2.7.0 release. We then dogfooded the develop branch (2.7.0a0) against CausalPy and confirmed:

• Citation hyperlinks now resolve to the same page when the citing notebook has its own :::{bibliography}::: block, even when other notebooks register the same key.
• Cross-document duplicate noise can be suppressed cleanly with suppress_warnings = ["bibtex.duplicate_citation"] while real same-page duplicates still surface via the new bibtex.duplicate_local_citation category.

What to do

Once sphinxcontrib-bibtex 2.7.0 is tagged on PyPI, undo the centralisation from #834 and restore per-document bibliographies.

Tasks

• Bump the docs extra in pyproject.toml to sphinxcontrib-bibtex>=2.7.0 (and regenerate environment.yml via the standard script).
• Add suppress_warnings = ["bibtex.duplicate_citation"] to docs/source/conf.py.
• Re-add a ## References markdown cell with :::{bibliography}:filter: docname in docnames::: to each of the ~22 documents that lost it in 3694557. Use nbformat-based tooling, not in-place notebook editors, to keep diffs clean.
• Decide whether to keep docs/source/references.rst as a global discoverability page (now safe — same-document resolution wins for citing pages) or remove it and the ../references toctree entry in docs/source/knowledgebase/index.md.
• Remove the orphan per-doc bibliography in docs/source/notebooks/panel_fixed_effects.ipynb (not removed in 3694557) and re-add it as part of the consistent rollout, so it is no longer an inconsistent special case.
• Build the docs locally (make html) and verify zero bibtex.duplicate_local_citation warnings; spot-check a handful of rendered pages to confirm citation links resolve to in-page anchors.

Blockers

• sphinxcontrib-bibtex 2.7.0 has not yet been released. Latest on PyPI is 2.6.5 (2025-06-27). The fix is on the develop branch as 2.7.0a0. Hold this issue until the tag lands.

References

• CausalPy PR that introduced the centralisation: docs: fix Sphinx build warnings #834 (commit 3694557)
• Upstream issue: mcmtroffaes/sphinxcontrib-bibtex#385
• Upstream fix: mcmtroffaes/sphinxcontrib-bibtex#387

[drbenvincent]

No expectation for you to do this with sphinxcontrib-bibtex 2.7.0 is released, but thought I'd tag you @anevolbap because this will undo some of your PR #834.

[anevolbap]

@drbenvincent, opened #909 to do the revert. The PR also fixes a goodman2021difference cite key typo it surfaced and supersedes #905 (panel_fixed_effects keeps its bibliography block under this approach). Filed #911 separately to suggest an automated check so this kind of cite key typo can be caught earlier.