Upon the first pass of the documentation compilation, undefined label warnings should not trigger an exception
Closed this issue · 18 comments
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
Description changed:
---
+++
@@ -1 +1,11 @@
+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.
+Author: Florent Hivert, Nicolas Thiéry
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 |
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 raiseThe (?!STRING) syntax matches anything except for STRING: see https://docs.python.org/2/library/re.html.
Branch pushed to git repo; I updated commit sha1. New commits:
fb43b19 | 17189: referee's suggestions: only undefined warnings don't trigger an exception |
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 |
I think this looks good now. Any objections from anyone else?
Reviewer: John Palmieri
Forgot your own middle initial, sir.
Changed author from Florent Hivert, Nicolas Thiéry to Florent Hivert, Nicolas M. Thiéry