Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

LaTeX: URLs as footnotes fail to show in PDF if originating from inside function type signatures #8750

Closed
jfbu opened this issue Jan 24, 2021 · 0 comments · Fixed by #8812
Closed

Comments

@jfbu
Copy link
Contributor

jfbu commented Jan 24, 2021

Describe the bug

LaTeX has configuration option latex_show_urls = 'footnote' which, additionally to having regular external hyperlinks in PDF also displays the URLs as text strings in footnotes. (This is with the idea of printed docs).

In the case of auto-generated documentation links, e.g. to Python documentation, which comes from function signatures, the footnote marker shows, but there is no footnote.

To Reproduce
Steps to reproduce the behavior:

Use attached project
missingfootnotes.zip

or directly this:

conf.py:

extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.intersphinx',
]

intersphinx_mapping = {
    'python': ('https://docs.python.org/3/', None),
}

latex_show_urls = 'footnote'

index.rst

Welcome to FOO's documentation!
===============================

TESTING FOR FAILED PDF RENDERING OF LINKS AS FOOTNOTES IN SIGNATURES
--------------------------------------------------------------------

.. module:: sphinx.ext.autodoc
   :synopsis: Include documentation from docstrings.

.. autofunction:: between

Execute make latexpdf. In produced PDF the Python str and bool are correct external hyperlinks to Python docs. Footnote markers appear next to them, but there are no footnotes at bottom of page.

Also the console output of latex build contains lines such as:

pdfTeX warning (dest): name{Hfootnote.3} has been referenced but does not exist
, replaced by a fixed one

Note: this applies to Sphinx own docs, with between 100 and 200 footnotes at least going missing.

Expected behavior

Either show the footnote, or do not include any footnote marker.

Environment info

  • OS: Mac
  • Python version: 3.6.8 (I do have 3.8 and 3.9...)
  • Sphinx version: tested with 3.x
  • Sphinx extensions: sphinx.ext.autodoc, sphinx.ext.intersphinx, but problem is in sphinx.sty
  • Extra tools: TeXLive 2020

Additional context

The problem is more general, it would probably show with any external link arising in the label of a description list item, which becomes in LaTeX code some

\item[.... the footnote is here in label...] foo bar

For signatures, Sphinx uses a fulllineitems environment in sphinx.sty. This problem can be fixed by adding \begin{savenotes} at start and \end{savenotes} at end. But this will catch all footnotes from all items, not only from their labels, and display them at bottom of last page in case the description list spans multiple pages in pdf.

I tried adding the \begin{savenotes} and \end{savenotes} only at each \item but this causes LaTeX build failure and I expect it is hard to make it work.

As per the Sphinx own PDF docs, it runs at 3.x to about 500 pages and I wonder if people actually need paper copy. Setting latex_show_urls = 'no' will fix it for Sphinx own docs.

@jfbu jfbu added this to the 3.5.0 milestone Feb 1, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 14, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants