docs: restore per-document bibliographies after sphinxcontrib-bibtex 2.7.0

[anevolbap]

Closes #870. Supersedes #905 (the panel_fixed_effects bibliography cell stays in place under this approach, so the cleanup PR is no longer needed).

Update (rebased onto main)

Rebased onto main after #840 renamed all how-to notebooks (underscore -> hyphenated) and added the gallery plus sphinxext.rediraffe redirects. Reconciliation in conf.py: kept the gallery, rediraffe, and main's suppress_warnings; dropped custom.css from html_css_files (kept gallery.css); still drop strip_citation_labels and set bibtex_default_style = "unsrt".

Two follow-on fixes surfaced during the rebase:

• The goodman2021difference cite-key typo is now fixed in this PR, not deferred.
• interrupted-time-series-causalpy-vs-causalimpact.ipynb (new on main, added after this PR was written) cited brodersen2015inferring with no per-doc bibliography. With references.rst removed, that citation no longer resolved, so the notebook got a bibliography cell too.

Verified with two local sphinx-build runs on the docs extra (resolves sphinxcontrib-bibtex 2.7.0): both exit 0, zero bibtex warnings of any kind, and duplicate_local_citation = 0 (the category is left unsuppressed, so it would surface any genuine same-page duplicate). prek passes on the changed files.

Why

#834 centralized 22 per-document :::{bibliography}::: blocks into a single global references.rst to silence bibtex.duplicate_citation warnings. The deeper reason was that on sphinxcontrib-bibtex 2.6.x, citation hyperlinks resolved non-deterministically across documents (a {cite:t} on page A could link to page B's bibliography). The trade-off was a UX regression: readers leaving the page they were on to see a reference.

sphinxcontrib-bibtex 2.7.0 (PyPI, 2026-05-06) addresses that with same-document-preferred resolution (upstream issue #385 / PR #387) and a new duplicate_local_citation warning category that lets us suppress only the cross-document noise.

Changes

• pyproject.toml: pin sphinxcontrib-bibtex>=2.7.0.
• docs/source/conf.py: keep main's suppress_warnings (toc.not_included, bibtex.duplicate_label, bibtex.duplicate_citation; same-page duplicates still surface as bibtex.duplicate_local_citation). Revert bibtex_default_style from "alpha" to "unsrt". Drop the strip_citation_labels extension and its _extensions path. Drop custom.css from html_css_files (the hanging-indent rule was tuned for the centralized page).
• Delete docs/source/_extensions/strip_citation_labels.py, docs/source/_static/custom.css, docs/source/references.rst. Drop ../references from the knowledgebase toctree.
• Restore ## References + :::{bibliography}:filter: docname in docnames::: across the how-to notebooks and knowledgebase docs. Notebooks that cite keys without a per-doc bib (structural_causal_models.ipynb, iv_vs_priors.ipynb, and interrupted-time-series-causalpy-vs-causalimpact.ipynb) also got one, since cross-doc resolution no longer covers them under same-document-first behavior.

Notebook handling

Edits use raw JSON manipulation that preserves each notebook's original indent and key ordering, so diffs are minimal: each touched notebook adds 11-12 lines (the new markdown cell only). Outputs were not re-executed because no code cell changed; the appended cell is markdown only.

Out of scope

• Issue Improve formatting of centralized references page after PR #834 merges #836 (APA-style formatting of the centralized page) was scoped to the page that this PR removes; close or re-evaluate after merge.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.51%. Comparing base (13af0ef) to head (521cfdf).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #909   +/-   ##
=======================================
  Coverage   95.51%   95.51%           
=======================================
  Files          98       98           
  Lines       15868    15868           
  Branches      931      931           
=======================================
  Hits        15157    15157           
  Misses        504      504           
  Partials      207      207           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[read-the-docs-community]

Documentation build overview

📚 causalpy | 🛠️ Build #33582316 | 📁 Comparing 521cfdf against latest (e14d731)

  🔍 Preview build  

516 files changed · + 121 added · ± 394 modified · - 1 deleted

+ Added

• notebooks/ancova-pymc.html
• notebooks/difference-in-differences-banks-pymc.html
• notebooks/difference-in-differences-pymc.html
• notebooks/difference-in-differences-sklearn.html
• notebooks/geolift-single-cell.html
• notebooks/instrumental-variables-pymc.html
• notebooks/instrumental-variables-variable-selection-priors.html
• notebooks/instrumental-variables-weak-instruments.html
• notebooks/interrupted-time-series-causalpy-vs-causalimpact.html
• notebooks/interrupted-time-series-comparative-pymc.html
• and 111 more...

± Modified

• 404.html
• genindex.html
• index.html
• py-modindex.html
• _modules/index.html
• api/index.html
• knowledgebase/custom_pymc_models.html
• knowledgebase/design_notation.html
• knowledgebase/estimands.html
• knowledgebase/index.html
• and 384 more...

- Deleted

• references.html

[drbenvincent]

Automated triage

Recommendation: review:high — no decision gate identified.

Why:

• Dependency change: pins sphinxcontrib-bibtex>=2.7.0 in pyproject.toml — affects the docs build environment.
• Deletes custom extensions and CSS, restores per-document bibliographies across 22+ files.
• All CI checks pass; PR is conflicted (DIRTY).

Review focus:

1. Verify that the sphinxcontrib-bibtex>=2.7.0 pin does not break the docs build on ReadTheDocs.
2. Confirm that duplicate_local_citation warnings correctly surface genuine same-page duplicates.
3. Check that the goodman2021difference typo (pre-existing broken reference) is noted and a follow-up is planned.

Confidence: high

[anevolbap]

Rebased onto main (was 60+ commits behind; #840 had renamed every how-to notebook). On the three focus points:

1. The sphinxcontrib-bibtex>=2.7.0 pin builds cleanly: two local sphinx-build runs on the docs extra (resolves bibtex 2.7.0) exit 0 with zero bibtex warnings. The RTD build on this push is pending.
2. duplicate_local_citation is left unsuppressed and reports 0, so it would surface a genuine same-page duplicate if one existed. duplicate_citation and duplicate_label stay suppressed as cross-doc noise.
3. The goodman2021difference typo is fixed in this PR, not deferred.

The rebase also exposed a regression: interrupted-time-series-causalpy-vs-causalimpact.ipynb (new on main, added after this PR was written) cited brodersen2015inferring with no per-doc bibliography, which stopped resolving once references.rst was removed. It now has a bibliography cell.