docs: restore per-document bibliographies after sphinxcontrib-bibtex 2.7.0#909
Open
anevolbap wants to merge 2 commits into
Open
docs: restore per-document bibliographies after sphinxcontrib-bibtex 2.7.0#909anevolbap wants to merge 2 commits into
anevolbap wants to merge 2 commits into
Conversation
…2.7.0 Reverts the centralization done in pymc-labs#834. With sphinxcontrib-bibtex 2.7.0 (released 2026-05-06), citation hyperlinks resolve to the same page when the citing document has its own bibliography block, even when other documents register the same key. This removes the UX regression that forced the central-page workaround. - pyproject.toml: pin sphinxcontrib-bibtex>=2.7.0 - conf.py: suppress duplicate_citation/duplicate_label, revert default style alpha->unsrt, drop strip_citation_labels extension and custom.css hanging-indent rule - delete _extensions/strip_citation_labels.py, _static/custom.css, references.rst - knowledgebase/index.md: drop ../references toctree entry - restore '## References' + bibliography block in 22 docs (3 markdown + 19 notebooks). Two extra notebooks that always cited keys without a per-doc bib (structural_causal_models.ipynb, iv_vs_priors.ipynb) now also have one, since cross-doc resolution no longer covers them by default. Closes pymc-labs#870.
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
github-actions
Bot
added
the
documentation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #909 +/- ##
==========================================
+ Coverage 94.87% 94.89% +0.01%
==========================================
Files 85 85
Lines 13174 13174
Branches 793 793
==========================================
+ Hits 12499 12501 +2
+ Misses 479 478 -1
+ Partials 196 195 -1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Documentation build overview
27 files changed ·
|
…ence The references.bib entry has always been goodmanbacon2021difference, but four citations across three docs used a misspelled goodman2021difference that had never resolved. Fixes the resulting bibtex.key_not_found warnings flagged during the per-document bibliography revert build.
This was referenced May 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #870. Supersedes #905 (the panel_fixed_effects bibliography cell stays in place under this approach, so the cleanup PR is no longer needed).
Why
#834 centralized 22 per-document
:::{bibliography}:::blocks into a single globalreferences.rstto silencebibtex.duplicate_citationwarnings. 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 newduplicate_local_citationwarning category that lets us suppress only the cross-document noise.Changes
pyproject.toml: pinsphinxcontrib-bibtex>=2.7.0.docs/source/conf.py: addsuppress_warnings = ["bibtex.duplicate_citation", "bibtex.duplicate_label"](both are expected noise across per-doc bibliographies; same-page duplicates still surface asbibtex.duplicate_local_citation). Revertbibtex_default_stylefrom"alpha"to"unsrt". Drop thestrip_citation_labelsextension and thecustom.csshanging-indent rule (both were tuned for the centralized page).docs/source/_extensions/strip_citation_labels.py,docs/source/_static/custom.css,docs/source/references.rst. Drop../referencesfrom the knowledgebase toctree.## References+:::{bibliography}:filter: docname in docnames:::in 22 docs (3 markdown, 19 notebooks). Two extra notebooks that previously cited keys without a per-doc bib (structural_causal_models.ipynb,iv_vs_priors.ipynb) also got one, since cross-doc resolution no longer covers them under same-document-first behavior.Notebook handling
Edits used 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.
Verification
prek run --all-filespasses locally.make htmlbuilds with 12 warnings, all of them pre-existing and unrelated:pymc.model.core.Model.debugdocstring ERRORs (PyMC source, also flagged in docs: fix Sphinx build warnings #834).bibtex.key_not_foundforgoodman2021differenceinpanel_fixed_effects.ipynb,sensitivity_checks.md, andstaggered_did_pymc.ipynb-- the actual key inreferences.bibisgoodmanbacon2021difference. This typo was already broken under the centralized page; out of scope for this PR.{cite:t}/{cite:p}links insc_pymc.html,did_pymc_banks.html,inv_prop_pymc.htmlresolve to in-page anchors (href="#idN"matchingid="idN"in the same document).bibtex.duplicate_local_citationwarnings.Out of scope
goodman2021differencetypo can be fixed in a follow-up PR.