Fix Sphinx (#6070)

Fixes #4686.

In Sphinx 1.6, they changed how they handle images in latex and PDF files. You can learn more about this by reading the linked issue (or I can answer any questions), but the shortish version is we now need to use the extension sphinx.ext.imgconverter. This is only available in Sphinx 1.6+.

I also updated our pinned versions to use the latest Sphinx and a new dependency it pulled in called sphinxcontrib-websupport. To build the latex and PDF docs, you must first run:

apt-get install imagemagick latexmk texlive texlive-latex-extra

Afterwards, if you create the normal Certbot dev environment using this branch, activate the virtual environment, and from the root of the repo run make -C docs clean latex latexpdf, you'll successfully build the PDF docs.

* fix #4686

* bump minimum Sphinx req

docs/conf.py

@@ -40,6 +40,7 @@ needs_sphinx = '1.0'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.imgconverter',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',

setup.py

@@ -70,8 +70,8 @@ dev3_extras = [
 
 docs_extras = [
     'repoze.sphinx.autointerface',
-    # autodoc_member_order = 'bysource', autodoc_default_flags, and #4686
-    'Sphinx >=1.0,<=1.5.6',
+    # sphinx.ext.imgconverter
+    'Sphinx >=1.6',
     'sphinx_rtd_theme',
 ]
 

tools/dev_constraints.txt

@@ -60,8 +60,9 @@ s3transfer==0.1.11
 scandir==1.6
 simplegeneric==0.8.1
 snowballstemmer==1.2.1
-Sphinx==1.5.6
+Sphinx==1.7.5
 sphinx-rtd-theme==0.2.4
+sphinxcontrib-websupport==1.0.1
 tldextract==2.2.0
 tox==2.9.1
 tqdm==4.19.4