Trac #26451: Upgrade to Sphinx 1.8.5

This ticket upgrades Sphinx to version 1.8.5.

Our previous upgrade was to Sphinx 1.7.6 in #26033.

'''Tarball''': https://files.pythonhosted.org/packages/2a/86/8e1e8400bb6
eca5ed960917952600fce90599e1cb0d20ddedd81ba163370/Sphinx-1.8.5.tar.gz

URL: https://trac.sagemath.org/26451
Reported by: saraedum
Ticket author(s): Julian Rüth, Jeroen Demeyer, John Palmieri, Tobias
Hansen
Reviewer(s): Dima Pasechnik

build/pkgs/sphinx/checksums.ini

@@ -1,4 +1,4 @@
 tarball=Sphinx-VERSION.tar.gz
-sha1=3caa8c2d3f9b283e32df259baee885c0340c5d02
-md5=8fbd77d80c8e0966964751ab31a0204a
-cksum=1266150694
+sha1=93e715cb5d16d981698caa2d54b3b58596798f5d
+md5=554f7a4e752f48b2601e5ef5ab463346
+cksum=2134440192

build/pkgs/sphinx/package-version.txt

@@ -1 +1 @@
-1.7.6.p1
+1.8.5.p0

build/pkgs/sphinx/patches/environment.patch

@@ -1,17 +1,16 @@
 Prevent Sphinx from rebuilding documentation that is already built
 
 diff -ru a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py
---- a/sphinx/environment/__init__.py	2017-05-15 19:15:50.000000000 +0200
-+++ b/sphinx/environment/__init__.py	2017-05-18 13:42:40.871043207 +0200
-@@ -512,8 +512,11 @@
+--- a/sphinx/environment/__init__.py   2017-05-15 19:15:50.000000000 +0200
++++ b/sphinx/environment/__init__.py   2017-05-18 13:42:40.871043207 +0200
+@@ -251,7 +251,10 @@
          else:
              # check if a config value was changed that affects how
              # doctrees are read
 +            import inspect
-             for confval in config.filter('env'):
-                 if self.config[confval.name] != confval.value:
-+                    if inspect.isfunction(confval.value):
-+                        continue
-                     msg = '[config changed] '
-                     config_changed = True
+             for item in config.filter('env'):
++                if inspect.isfunction(item.value):
++                    continue
+                 if self.config[item.name] != item.value:
+                     self.config_status = CONFIG_CHANGED
                      break

src/doc/common/conf.py

@@ -688,7 +688,7 @@ def call_intersphinx(app, env, node, contnode):
         sage: for line in open(thematic_index).readlines():  # optional - dochtml
         ....:     if "padics" in line:
         ....:         _ = sys.stdout.write(line)
-        <li><a class="reference external" href="../reference/padics/sage/rings/padics/tutorial.html#sage-rings-padics-tutorial" title="(in Sage Reference Manual: p-Adics v...)"><span>Introduction to the -adics</span></a></li>
+        <li><a class="reference external" href="../reference/padics/sage/rings/padics/tutorial.html#sage-rings-padics-tutorial" title="(in Sage Reference Manual: p-Adics v...)"><span>Introduction to the p-adics</span></a></li>
     """
     debug_inf(app, "???? Trying intersphinx for %s" % node['reftarget'])
     builder = app.builder

src/sage/misc/sphinxify.py

@@ -68,20 +68,20 @@ def sphinxify(docstring, format='html'):
         sage: assert n == len(sys.path)
     """
     srcdir = mkdtemp()
-    base_name = os.path.join(srcdir, 'docstring')
-    rst_name = base_name + '.rst'
+    outdir = mkdtemp()
+    src_base_name = os.path.join(srcdir, 'docstring')
+    out_base_name = os.path.join(outdir, 'docstring')
+    rst_name = src_base_name + '.rst'
 
     if format == 'html':
         suffix = '.html'
     else:
         suffix = '.txt'
-    output_name = base_name + suffix
+    output_name = out_base_name + suffix
 
     with open(rst_name, 'w') as filed:
         filed.write(docstring)
 
-    # Sphinx constructor: Sphinx(srcdir, confdir, outdir, doctreedir,
-    # buildername, confoverrides, status, warning, freshenv).
     confdir = os.path.join(SAGE_DOC_SRC, 'en', 'introspect')
 
     open(os.path.join(srcdir, 'docutils.conf'), 'w').write(r"""
@@ -93,7 +93,9 @@ def sphinxify(docstring, format='html'):
 
     import sys
     old_sys_path = list(sys.path)  # Sphinx modifies sys.path
-    sphinx_app = Sphinx(srcdir, confdir, srcdir, doctreedir, format,
+    # Sphinx constructor: Sphinx(srcdir, confdir, outdir, doctreedir,
+    # buildername, confoverrides, status, warning, freshenv).
+    sphinx_app = Sphinx(srcdir, confdir, outdir, doctreedir, format,
                         confoverrides, None, None, True)
     sphinx_app.build(None, [rst_name])
     sys.path = old_sys_path
@@ -118,13 +120,15 @@ def sphinxify(docstring, format='html'):
         # Remove spurious \(, \), \[, \].
         output = output.replace('\\(', '').replace('\\)', '').replace('\\[', '').replace('\\]', '')
     else:
-        print("BUG -- Sphinx error")
+        from warnings import warn
+        warn("Sphinx did not produce any output", Warning)
         if format == 'html':
             output = '<pre class="introspection">%s</pre>' % docstring
         else:
             output = docstring
 
     shutil.rmtree(srcdir, ignore_errors=True)
+    shutil.rmtree(outdir, ignore_errors=True)
 
     return output
 

src/sage_setup/docbuild/__init__.py

@@ -53,7 +53,6 @@
 
 logger = logging.getLogger(__name__)
 
-import sphinx.cmdline
 import sphinx.util.console
 import sphinx.ext.intersphinx
 
@@ -352,6 +351,7 @@ def _wrapper(self, name, *args, **kwds):
             getattr(get_builder(document), 'inventory')(*args, **kwds)
 
         logger.warning("Building reference manual, second pass.\n")
+        sage_makedirs(os.path.join(SAGE_DOC, "html", "en", "reference", "_static"))
         for document in refs:
             getattr(get_builder(document), name)(*args, **kwds)
 

src/sage_setup/docbuild/ext/inventory_builder.py

@@ -12,6 +12,7 @@
 
 from six import iteritems, text_type
 
+import shutil
 
 try:
     from hashlib import md5
@@ -107,6 +108,18 @@ def removed_method_error(self):
         """
         raise RuntimeError("This function shouldn't be called in \"%s\" builder"%(self.name))
 
+    def cleanup(self):
+        """
+        Remove the '_static' directory.
+
+        This directory is unnecessary for the inventory build, but it
+        may be created by the graphviz extension. Its presence will
+        break the docbuild later on, so remove it.
+        """
+        if path.isdir(path.join(self.outdir, '_static')):
+            shutil.rmtree(path.join(self.outdir, '_static'))
+
+
     copy_image_files = removed_method_error
     copy_download_files = removed_method_error
     copy_static_files = removed_method_error

src/sage_setup/docbuild/ext/multidocs.py

@@ -32,6 +32,7 @@
 from sage.env import SAGE_DOC
 from sage.misc.misc import sage_makedirs
 
+logger = sphinx.util.logging.getLogger(__name__)
 
 CITE_FILENAME = 'citations.pickle'
 
@@ -48,13 +49,13 @@ def merge_environment(app, env):
 
     - domaindata['py']['modules'] # list of python modules
     """
-    app.info(bold('Merging environment/index files...'))
+    logger.info(bold('Merging environment/index files...'))
     for curdoc in app.env.config.multidocs_subdoc_list:
-        app.info("    %s:" % curdoc, nonl=1)
+        logger.info("    %s:"%curdoc, nonl=1)
         docenv = get_env(app, curdoc)
         if docenv is not None:
             fixpath = lambda path: os.path.join(curdoc, path)
-            app.info(" %s todos, %s index, %s citations"%(
+            logger.info(" %s todos, %s index, %s citations"%(
                     len(docenv.todo_all_todos),
                     len(docenv.indexentries),
                     len(docenv.domaindata["std"]["citations"])
@@ -99,8 +100,8 @@ def merge_environment(app, env):
                 six.iteritems(docenv.domaindata['py']['modules'])):
                 newmodules[ind] = (fixpath(modpath),v1,v2,v3)
             env.domaindata['py']['modules'].update(newmodules)
-            app.info(", %s modules"%(len(newmodules)))
-    app.info('... done (%s todos, %s index, %s citations, %s modules)'%(
+            logger.info(", %s modules"%(len(newmodules)))
+    logger.info('... done (%s todos, %s index, %s citations, %s modules)'%(
             len(env.todo_all_todos),
             len(env.indexentries),
             len(env.domaindata["std"]["citations"]),
@@ -118,8 +119,8 @@ def get_env(app, curdoc):
     try:
         f = open(filename, 'rb')
     except IOError:
-        app.info("")
-        app.warn("Unable to fetch %s " % filename)
+        logger.info("")
+        logger.warning("Unable to fetch %s " % filename)
         return None
     docenv = cPickle.load(f)
     f.close()
@@ -130,16 +131,16 @@ def merge_js_index(app):
     """
     Merge the JS indexes of the sub-docs into the main JS index
     """
-    app.info('')
-    app.info(bold('Merging js index files...'))
+    logger.info('')
+    logger.info(bold('Merging js index files...'))
     mapping = app.builder.indexer._mapping
     for curdoc in app.env.config.multidocs_subdoc_list:
-        app.info("    %s:"%curdoc, nonl=1)
+        logger.info("    %s:"%curdoc, nonl=1)
         fixpath = lambda path: os.path.join(curdoc, path)
         index = get_js_index(app, curdoc)
         if index is not None:
             # merge the mappings
-            app.info(" %s js index entries"%(len(index._mapping)))
+            logger.info(" %s js index entries"%(len(index._mapping)))
             for (ref, locs) in six.iteritems(index._mapping):
                 newmapping = set(map(fixpath, locs))
                 if ref in mapping:
@@ -159,8 +160,8 @@ def merge_js_index(app):
             dest = os.path.join(app.outdir, "_sources", curdoc)
             if not os.path.exists(dest):
                 os.symlink(os.path.join("..", curdoc, "_sources"), dest)
-    app.info('... done (%s js index entries)'%(len(mapping)))
-    app.info(bold('Writing js search indexes...'), nonl=1)
+    logger.info('... done (%s js index entries)'%(len(mapping)))
+    logger.info(bold('Writing js search indexes...'), nonl=1)
     return [] # no extra page to setup
 
 
@@ -181,8 +182,8 @@ def get_js_index(app, curdoc):
     try:
         f = open(indexfile, 'r')
     except IOError:
-        app.info("")
-        app.warn("Unable to fetch %s " % indexfile)
+        logger.info("")
+        logger.warning("Unable to fetch %s " % indexfile)
         return None
     indexer.load(f, sphinx.search.js_index)
     f.close()
@@ -240,21 +241,21 @@ def write_citations(app, citations):
     outdir = citation_dir(app)
     with atomic_write(os.path.join(outdir, CITE_FILENAME), binary=True) as f:
         cPickle.dump(citations, f)
-    app.info("Saved pickle file: %s" % CITE_FILENAME)
+    logger.info("Saved pickle file: %s" % CITE_FILENAME)
 
 
 def fetch_citation(app, env):
     """
     Fetch the global citation index from the refman to allow for cross
     references.
     """
-    app.builder.info(bold('loading cross citations... '), nonl=1)
+    logger.info(bold('loading cross citations... '), nonl=1)
     filename = os.path.join(citation_dir(app), '..', CITE_FILENAME)
     if not os.path.isfile(filename):
         return
     with open(filename, 'rb') as f:
         cache = cPickle.load(f)
-    app.builder.info("done (%s citations)."%len(cache))
+    logger.info("done (%s citations)."%len(cache))
     cite = env.domaindata["std"]["citations"]
     for ind, (path, tag, lineno) in six.iteritems(cache):
         if ind not in cite: # don't override local citation
@@ -267,18 +268,18 @@ def init_subdoc(app):
     doc itself.
     """
     if app.config.multidocs_is_master:
-        app.info(bold("Compiling the master document"))
+        logger.info(bold("Compiling the master document"))
         app.connect('env-updated', merge_environment)
         app.connect('html-collect-pages', merge_js_index)
         if app.config.multidocs_subdoc_list:
             # Master file with indexes computed by merging indexes:
             # Monkey patch index fetching to silence warning about broken index
             def load_indexer(docnames):
-                app.builder.info(bold('skipping loading of indexes... '), nonl=1)
+                logger.info(bold('skipping loading of indexes... '), nonl=1)
             app.builder.load_indexer = load_indexer
 
     else:
-        app.info(bold("Compiling a sub-document"))
+        logger.info(bold("Compiling a sub-document"))
         app.connect('html-page-context', fix_path_html)
         if not app.config.multidoc_first_pass:
             app.connect('env-updated', fetch_citation)
@@ -294,7 +295,7 @@ class StandaloneHTMLBuilder(Builder):
                     def copy_static_files(self):
                     [...]
             """
-            app.builder.info(bold('linking _static directory.'))
+            logger.info(bold('linking _static directory.'))
             static_dir = os.path.join(app.builder.outdir, '_static')
             master_static_dir = os.path.join('..', '_static')
             if os.path.lexists(static_dir):
@@ -308,6 +309,9 @@ def copy_static_files(self):
 
     if app.config.multidoc_first_pass == 1:
         app.config.intersphinx_mapping = {}
+    else:
+        app.emit('env-check-consistency', app.env)
+
 
 
 def setup(app):

src/sage_setup/docbuild/ext/sage_autodoc.py

@@ -40,7 +40,8 @@
 from sphinx.ext.autodoc.importer import mock, import_object, get_object_members
 from sphinx.ext.autodoc.inspector import format_annotation, formatargspec
 from sphinx.locale import _, __
-from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.pycode import ModuleAnalyzer
+from sphinx.errors import ExtensionError, PycodeError
 from sphinx.util import logging
 from sphinx.util import rpartition, force_decode
 from sphinx.util.docstrings import prepare_docstring

src/sage_setup/docbuild/sphinxbuild.py

@@ -22,6 +22,7 @@
 # ****************************************************************************
 
 import os, sys, re, sphinx
+import sphinx.cmd.build
 
 # override the fancy multi-line formatting
 def term_width_line(text):
@@ -304,12 +305,12 @@ def runsphinx():
     try:
         sys.stdout = SageSphinxLogger(sys.stdout, os.path.basename(output_dir))
         sys.stderr = SageSphinxLogger(sys.stderr, os.path.basename(output_dir))
-        # Note that this call as of eraly 2018 leaks memory. So make sure that
+        # Note that this call as of early 2018 leaks memory. So make sure that
         # you don't call runsphinx() several times in a row. (i.e., you want to
         # fork() somewhere before this call.)
         # We don't use subprocess here, as we don't want to re-initialize Sage
         # for every docbuild as this takes a while.
-        sphinx.cmdline.main(sys.argv[1:])
+        sphinx.cmd.build.main(sys.argv[1:])
         sys.stderr.raise_errors()
         sys.stdout.raise_errors()
     finally: