sphinx-doc / sphinx-doc/sphinx

Latex bibliography doublings handling

Open
#8,918 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Problem
When citing something more than once in the documentation with the same label, it will occur multiple times in the bibliography output in latex.

This can be seen for example in the Numpy documentation: https://numpy.org/doc/1.20/numpy-ref.pdf

On page 1811:

[1]: G. H. Golub and C. F. Van Loan,Matrix Computations, 3rd ed., Baltimore, MD, Johns Hopkins University Press,1996, pg. 8.
[1]: G. H. Golub and C. F. Van Loan,Matrix Computations, 3rd ed., Baltimore, MD, Johns Hopkins University Press,1996, pg. 8.

This is totally redundant and non-informative.

Describe the solution you'd like
It would be nice to have an option, to only show the first occurrence of a label in the bibliography to get the opportunity to have a non-redundant bibliography by using one-to-one labels ([Golub1996] for example for the situation given above)

This could be a simple switch in the conf.py:

latex_bibliography_single_lables = True

This should be False by default to keep the current behavior.

Additional context
This of course would mess up references that have the same label (e.g. the often used [1]), but this should then be handled by the user. It would be nice to get the ability to clean up the bibliography without switching to a bibtex file.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the conf.py configuration described in the issue and trace the LaTeX bibliography generation path that produces duplicate labels. Compare the generated output with the NumPy example, then add coverage showing that repeated labels can be emitted only once while the default behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.