Trac #17189: Upon the first pass of the documentation compilation, un…

…defined label warnings should not trigger an exception

Currently, any warning during the documentation compilation causes an
exception which stops the compilation.

This prevents adding certain cross links in the reference
manual. Indeed an undefined warning is issued during the first pass of
the compilation whenever some document A cross links to some document
B while A happens to be compiled before document B.

With this ticket, warnings during the first pass of compilation don't
trigger an exception any more. This ticket also adds a cross link from
sage.dynamics to sage.combinat to illustrate and test the issue.

URL: http://trac.sagemath.org/17189
Reported by: nthiery
Ticket author(s): Florent Hivert, Nicolas Thiéry
Reviewer(s): John Palmieri

src/doc/common/custom-sphinx-build.py

@@ -49,16 +49,24 @@ def term_width_line(text):
 
 # warnings: regular expressions (or strings) indicating a problem with
 # docbuilding. Raise an exception if any of these occur.
-
 warnings = (re.compile('Segmentation fault'),
             re.compile('SEVERE'),
             re.compile('ERROR'),
             re.compile('^make.*Error'),
             re.compile('Exception occurred'),
             re.compile('Sphinx error'))
 
+# We want all warnings to actually be errors.
+# Exceptions:
+# - warnings upon building the LaTeX documentation
+# - undefined labels upon the first pass of the compilation: some
+#   cross links may legitimately not yet be resolvable at this point.
 if 'latex' not in sys.argv:
-    warnings += (re.compile('WARNING'),)
+    if 'multidoc_first_pass=1' in sys.argv:
+        # Catch all warnings except 'WARNING: undefined label'
+        warnings += (re.compile('WARNING: (?!undefined label)'),)
+    else:
+        warnings += (re.compile('WARNING:'),)
 
 
 # Do not error out at the first warning, sometimes there is more

src/doc/en/reference/dynamics/index.rst

@@ -7,4 +7,8 @@ Discrete dynamics
    interval_exchanges
    flat_surfaces
 
+.. SEEALSO::
+
+    - :ref:`sage.combinat.e_one_star`
+
 .. include:: ../footer.txt