Skip to content

Improve formatting of centralized references page after PR #834 merges #836

@drbenvincent

Description

@drbenvincent

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions