numpy / numpy/numpydoc

Numpydoc does not play nice with 'latex' builder wrt bibliographic references

Open
#30 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

The way in which numpydoc manages bibliographic references is causing me some problems in conjunction with the latex sphinx builder.

  1. Whenever I have an automodule directive, all the docstrings of all the functions in the module seem to be parsed, even if the automodule directive does not have the option to document its members set. This causes the reference counter to be incremented every time it finds a bibliographic entry even if that entry is eventually not used. Eventually one gets bibliographic references with 'holes' in their numeric sequence. For instance, one may have [R5] and [R9] but not [R6], [R7], [R8]. This may go unnoticed in html output, but does not in latex output that collects all the references together.

  2. Because the source files are read in arbitrary order by sphinx, the reference counter is also incremented in arbitrary order. This means that in the final document [R5] can come before [R1]. While this may go almost unnoticed in html output, it is extremely bad in the latex output that collects all the references together.

  3. If I have a 'Reference' section in the documentation of a function, that section gets emptied when using the latex builder, because the latex buider collects all the references in a reference section at the end of the document. This leaves empty reference sections.

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 by reproducing the issue with an automodule directive and Sphinx's latex builder, focusing on bibliographic references and function Reference sections. Check whether unused references affect numbering, whether numbering depends on source-file order, and whether function-level sections become empty. Done means the LaTeX output has contiguous, stable references and no empty Reference sections.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.