#516: Added new value of the :confval:latex_show_urls option to show the URLs in footnotes.

CHANGES

@@ -46,6 +46,9 @@ Release 1.1 (in development)
 
 * #521: Added :confval:`linkcheck_ignore` config value.
 
+* #516: Added new value of the :confval:`latex_show_urls` option to
+  show the URLs in footnotes.
+
 * #526: Added Iranian translation.
 
 * #559: :confval:`html_add_permalinks` is now a string giving the

doc/conf.py

@@ -44,6 +44,7 @@ latex_logo = '_static/sphinx.png'
 latex_elements = {
     'fontpkg': '\\usepackage{palatino}',
 }
+latex_show_urls = 'footnote'
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True

doc/config.rst

@@ -933,10 +933,18 @@ These options influence LaTeX output.
 
 .. confval:: latex_show_urls
 
-   If true, add URL addresses after links.  This is very useful for printed
-   copies of the manual.  Default is ``False``.
+   Control whether to display URL addresses.  This is very useful for printed
+   copies of the manual.  The setting can have the following values:
+
+   * ``'no'`` -- do not display URLs (default)
+   * ``'footnote'`` -- display URLs in footnotes
+   * ``'inline'`` -- display URLs inline in parentheses
 
    .. versionadded:: 1.0
+   .. versionchanged:: 1.1
+      This value is now a string; previously it was a boolean value, and a true
+      value selected the ``'inline'`` display.  For backwards compatibility,
+      ``True`` is still accepted.
 
 .. confval:: latex_elements
 

sphinx/config.py

@@ -143,7 +143,7 @@ class Config(object):
         latex_use_parts = (False, None),
         latex_use_modindex = (True, None),  # deprecated
         latex_domain_indices = (True, None),
-        latex_show_urls = (False, None),
+        latex_show_urls = ('no', None),
         latex_show_pagerefs = (False, None),
         # paper_size and font_size are still separate values
         # so that you can give them easily on the command line

sphinx/roles.py

@@ -285,6 +285,7 @@ def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
         entries = [('single', target, targetid, target)]
     indexnode = addnodes.index()
     indexnode['entries'] = entries
+    indexnode['inline'] = True
     textnode = nodes.Text(title, title)
     return [indexnode, targetnode, textnode], []
 

sphinx/writers/latex.py

@@ -242,6 +242,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.verbatim = None
         self.in_title = 0
         self.in_production_list = 0
+        self.in_footnote = 0
+        self.in_caption = 0
         self.first_document = 1
         self.this_is_the_title = 1
         self.literal_whitespace = 0
@@ -594,9 +596,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
         raise nodes.SkipNode
 
     def visit_collected_footnote(self, node):
+        self.in_footnote += 1
         self.body.append('\\footnote{')
     def depart_collected_footnote(self, node):
         self.body.append('}')
+        self.in_footnote -= 1
 
     def visit_label(self, node):
         if isinstance(node.parent, nodes.citation):
@@ -815,7 +819,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def visit_paragraph(self, node):
         self.body.append('\n')
     def depart_paragraph(self, node):
-        self.body.append('\n\n')
+        self.body.append('\n')
 
     def visit_centered(self, node):
         self.body.append('\n\\begin{center}')
@@ -946,9 +950,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.body.append(self.context.pop())
 
     def visit_caption(self, node):
+        self.in_caption += 1
         self.body.append('\\caption{')
     def depart_caption(self, node):
         self.body.append('}')
+        self.in_caption -= 1
 
     def visit_legend(self, node):
         self.body.append('{\\small ')
@@ -1091,11 +1097,17 @@ class LaTeXTranslator(nodes.NodeVisitor):
                  uri.startswith('https:') or uri.startswith('ftp:'):
             self.body.append('\\href{%s}{' % self.encode_uri(uri))
             # if configured, put the URL after the link
-            if self.builder.config.latex_show_urls and \
-                   node.astext() != uri:
+            show_urls = self.builder.config.latex_show_urls
+            if node.astext() != uri and show_urls and show_urls != 'no':
                 if uri.startswith('mailto:'):
                     uri = uri[7:]
-                self.context.append('} (%s)' % self.encode_uri(uri))
+                if show_urls == 'footnote' and not \
+                   (self.in_footnote or self.in_caption):
+                    # obviously, footnotes in footnotes are not going to work
+                    self.context.append(
+                        r'}\footnote{%s}' % self.encode_uri(uri))
+                else:  # all other true values (b/w compat)
+                    self.context.append('} (%s)' % self.encode_uri(uri))
             else:
                 self.context.append('}')
         elif uri.startswith('#'):
@@ -1221,6 +1233,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if used:
             self.body.append('\\footnotemark[%s]' % num)
         else:
+            if self.in_caption:
+                raise UnsupportedError('%s:%s: footnotes in float captions '
+                                       'are not supported by LaTeX' %
+                                       (self.curfilestack[-1], node.line))
             footnode.walkabout(self)
             self.footnotestack[-1][num][1] = True
         raise nodes.SkipChildren