1

I'm using sphinx to generate the documentation of a python project and I'm making heavy use of external links. I'd like to build html and latexpdf outputs with these as clickable links (which is the default), but also a PDF version that will be printed, with these links showing up in footnotes.

In short: is there a way to write external links in a .rst file like this:

Ask a question on `my favorite Q&A website <http://stackoverflow.com/>`_.

and have a special output that will interpret this as if it was a footnote written like this:

Ask a question on my favorite Q&A website [#SO]_.

.. [#SO] http://stackoverflow.com/

while keeping the normal behavior (clickable link without a footnote) in other outputs?

Dettorer
  • 1,247
  • 1
  • 8
  • 26
  • 1
    Can you work with the solutions mentioned in http://stackoverflow.com/questions/7250659/python-code-to-generate-part-of-sphinx-documentation-is-it-possible? One of the answers mention Sphinx can use custom written extensions. – Jongware Dec 26 '14 at 12:32

1 Answers1

3

Jongware's comment made me look at parts of the sphinx documentation I didn't see, and I realized there actually is a configuration variable that does what I want:

latex_show_urls = 'footnote'

As I wanted to be able to generate the usual pdf and the one with the footnotes without changing the conf.py file, I left the default value and added the following rule to the sphinx's Makefile:

.PHONY: printpdf
printpdf: SPHINXOPTS+=-Dlatex_show_urls=footnote
printpdf: latexpdf

This rule calls the regular latexpdf rule, adding -Dlatex_show_urls=footnote to the options given to sphinx-build.

With this, we can generate the PDF to be printed (with footnotes) with:

make printpdf

And if we want a regular PDF, without the potentially numerous and (here) useless footnotes, the regular rule still does it:

make latexpdf
Dettorer
  • 1,247
  • 1
  • 8
  • 26
  • 1
    I hope I made this answer a bit useful, as I feel bad for not seeing the simple option that does just exactly what I wanted… – Dettorer Dec 26 '14 at 13:14
  • 1
    @Jongware I'll do it, there's just a two limit before you can accept your own answer. – Dettorer Dec 27 '14 at 01:10