Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#17189 closed defect (fixed)

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

Reported by: nthiery Owned by:
Priority: major Milestone: sage-6.4
Component: documentation Keywords:
Cc: hivert, jhpalmieri, sage-combinat, vbraun Merged in:
Authors: Florent Hivert, Nicolas M. Thiéry Reviewers: John Palmieri
Report Upstream: N/A Work issues:
Branch: fb43b19 (Commits, GitHub, GitLab) Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by 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.

Change History (12)

comment:1 Changed 6 years ago by nthiery

  • Branch set to u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception

comment:2 Changed 6 years ago by nthiery

  • Authors set to Florent Hivert, Nicolas Thiéry
  • Branch u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception deleted
  • Cc hivert jhpalmieri sage-combinat vbraun added
  • Component changed from PLEASE CHANGE to documentation
  • Description modified (diff)
  • Status changed from new to needs_review
  • Type changed from PLEASE CHANGE to defect

comment:3 Changed 6 years ago by nthiery

This is needed for #16256.

comment:4 Changed 6 years ago by nthiery

  • Branch set to u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception

comment:5 Changed 6 years ago by nthiery

  • Commit set to b7e0a696a4d9737ff361e209be6c99b7e08d5a69

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


New commits:

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

comment:6 Changed 6 years ago by jhpalmieri

  • Status changed from needs_review to needs_work

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:

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

    diff --git a/src/doc/common/custom-sphinx-build.py b/src/doc/common/custom-sphinx-build.py
    index 712694e..f1b48fa 100644
    a b warnings = (re.compile('Segmentation fault'), 
    5858# Unless this is the first pass of the compilation (where some cross
    5959# links may not be resolvable yet), or we are compiling the latex
    6060# documentation, we want all warnings to raise an exception.
    61 if 'multidoc_first_pass=1' not in sys.argv and 'latex' not in sys.argv:
    62     warnings += (re.compile('WARNING'),)
    63 
     61if 'latex' not in sys.argv:
     62    if 'multidoc_first_pass=1' in sys.argv:
     63        # Catch all warnings except 'WARNING: undefined label'
     64        warnings += (re.compile('WARNING: (?!undefined label)'),)
     65    else:
     66        warnings += (re.compile('WARNING:'),)
    6467
    6568# Do not error out at the first warning, sometimes there is more
    6669# 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.

comment:7 Changed 6 years ago by git

  • Commit changed from b7e0a696a4d9737ff361e209be6c99b7e08d5a69 to fb43b1946ab3f7e5de66e0bc1eb885c9173ba2c3

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

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

comment:8 Changed 6 years ago by nthiery

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


New commits:

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

comment:9 Changed 6 years ago by jhpalmieri

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

comment:10 Changed 6 years ago by jhpalmieri

  • Reviewers set to John Palmieri
  • Status changed from needs_work to positive_review

comment:11 Changed 6 years ago by vbraun

  • Branch changed from u/nthiery/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception to fb43b1946ab3f7e5de66e0bc1eb885c9173ba2c3
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:12 Changed 6 years ago by kcrisman

  • Authors changed from Florent Hivert, Nicolas Thiéry to Florent Hivert, Nicolas M. Thiéry
  • Commit fb43b1946ab3f7e5de66e0bc1eb885c9173ba2c3 deleted

Forgot your own middle initial, sir.

Note: See TracTickets for help on using tickets.