Summary
Follow up on the centralized bibliography introduced in PR #834 by improving the rendering of the new References page.
Motivation
PR #834 consolidates per-page bibliography blocks into a single shared docs/source/references.rst page to eliminate duplicate citation warnings during the Sphinx build. That is a sensible cleanup, but it also makes the presentation of the bibliography much more visible to readers.
The bibliography might be easier to scan if entries were formatted more like a conventional APA-style reference list, with surnames first and alphabetical ordering that is visually obvious.
This is not just a markup change inside docs/source/references.rst. The proposed :style: apa7 setting requires an additional pybtex style plugin, so follow-up work will also need to add and install a new docs dependency before the docs build can succeed with APA-style formatting.
This should be treated as follow-up work after PR #834 is merged, since the centralized References page only exists once that PR lands.
Proposed direction
- Evaluate switching the centralized bibliography to an APA-like formatting style so author names render surname-first.
- Consider rendering the bibliography as a bullet list rather than a citation-style list, so labels like
[Aba21] are not shown.
- Keep the current author-year inline citation style unless there is a strong reason to change it.
Possible implementation
- Add an APA-compatible pybtex formatting plugin to the docs dependencies, for example
pybtex-apa7-style, by updating the docs extras in pyproject.toml.
- Reinstall or refresh the docs environment so the new plugin is available during the Sphinx build.
- Update
docs/source/references.rst to use:
.. bibliography::
:style: apa7
:list: bullet
- Build the docs and confirm the resulting
References page is easier to scan and that inline citations still render acceptably.
Acceptance criteria
- The required APA-style pybtex plugin is added to the docs dependencies and available in the docs build environment.
- The centralized
References page is formatted in a more reader-friendly way.
- Entries render surname-first in an APA-like style.
- Labels such as
[Aba21] are not shown.
- The page reads as an alphabetized reference list rather than a list of citation labels.
make html succeeds after the change.
Summary
Follow up on the centralized bibliography introduced in PR #834 by improving the rendering of the new
Referencespage.Motivation
PR #834 consolidates per-page bibliography blocks into a single shared
docs/source/references.rstpage to eliminate duplicate citation warnings during the Sphinx build. That is a sensible cleanup, but it also makes the presentation of the bibliography much more visible to readers.The bibliography might be easier to scan if entries were formatted more like a conventional APA-style reference list, with surnames first and alphabetical ordering that is visually obvious.
This is not just a markup change inside
docs/source/references.rst. The proposed:style: apa7setting requires an additional pybtex style plugin, so follow-up work will also need to add and install a new docs dependency before the docs build can succeed with APA-style formatting.This should be treated as follow-up work after PR #834 is merged, since the centralized
Referencespage only exists once that PR lands.Proposed direction
[Aba21]are not shown.Possible implementation
pybtex-apa7-style, by updating thedocsextras inpyproject.toml.docs/source/references.rstto use:Referencespage is easier to scan and that inline citations still render acceptably.Acceptance criteria
Referencespage is formatted in a more reader-friendly way.[Aba21]are not shown.make htmlsucceeds after the change.