Upon the first pass of the documentation compilation, undefined label warnings should not trigger an exception

[nthiery]

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.

CC: @hivert @jhpalmieri @sagetrac-sage-combinat @vbraun

Component: documentation

Author: Florent Hivert, Nicolas M. Thiéry

Branch: fb43b19

Reviewer: John Palmieri

Issue created by migration from https://trac.sagemath.org/ticket/17189

[nthiery]

Branch: u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception

[nthiery]

Author: Florent Hivert, Nicolas Thiéry

[nthiery]

Changed branch from u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception to none

[nthiery]

comment:3

This is needed for #16256.

[nthiery]

Branch: u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception

[nthiery]

comment:5

When read aloud in French, this is a revolutionary ticket number :-)

---

New commits:

b7e0a69

17189: upon the first pass of the documentation compilation, warnings don't trigger an exception

[nthiery]

Commit: b7e0a69

[jhpalmieri]

comment:6

The problem with ignoring warnings is that you're ignoring warnings, so badly formatted documentation builds without an error. I tested by misformatting some documentation and running make. In the docbuilding log, I saw a line like

WARNING: Block quote ends without a blank line; unexpected unindent.

on the first pass, not the second, and as a result, the documentation claimed to build successfully. How about something like this instead:

diff --git a/src/doc/common/custom-sphinx-build.py b/src/doc/common/custom-sphinx-build.py
index 712694e..f1b48fa 100644
--- a/src/doc/common/custom-sphinx-build.py
+++ b/src/doc/common/custom-sphinx-build.py
@@ -58,9 +58,12 @@ warnings = (re.compile('Segmentation fault'),
 # Unless this is the first pass of the compilation (where some cross
 # links may not be resolvable yet), or we are compiling the latex
 # documentation, we want all warnings to raise an exception.
-if 'multidoc_first_pass=1' not in sys.argv and 'latex' not in sys.argv:
-    warnings += (re.compile('WARNING'),)
-
+if 'latex' not in sys.argv:
+    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
 # information. So we run until the end of the file and only then raise

The (?!STRING) syntax matches anything except for STRING: see https://docs.python.org/2/library/re.html.

[sagetrac-git]

Changed commit from b7e0a69 to fb43b19

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

fb43b19

17189: referee's suggestions: only undefined warnings don't trigger an exception

[nthiery]

comment:8

Ah, good catch, I thought those warnings would be reissued upon the second pass. In that case, sure, this looks good.

---

New commits:

fb43b19

17189: referee's suggestions: only undefined warnings don't trigger an exception

[jhpalmieri]

comment:9

I think this looks good now. Any objections from anyone else?

[jhpalmieri]

Reviewer: John Palmieri

[vbraun]

Changed branch from u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception to fb43b19

[kcrisman]

comment:12

Forgot your own middle initial, sir.

[kcrisman]

Changed commit from fb43b19 to none

[kcrisman]

Changed author from Florent Hivert, Nicolas Thiéry to Florent Hivert, Nicolas M. Thiéry