Numpydoc does not play nice with 'latex' builder wrt bibliographic references
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.
-
Whenever I have an
automoduledirective, 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. -
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.
-
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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