Opened 6 years ago

Closed 6 years ago

#16100 closed enhancement (fixed)

Keep going in doc errors

Reported by: vbraun Owned by:
Priority: major Milestone: sage-6.2
Component: documentation Keywords: days57
Cc: ncohen, ​jhpalmieri Merged in:
Authors: Volker Braun Reviewers: Nicolas M. Thiéry
Report Upstream: N/A Work issues:
Branch: 1e7bc36 (Commits) Commit: 1e7bc36e6ecda3e167bb12b1b78c87dc41b8fa82
Dependencies: Stopgaps:

Description (last modified by vbraun)

$ sage -docbuild -h
Usage: sage -docbuild [OPTIONS] DOCUMENT (FORMAT | COMMAND)

[...]

  Advanced:
    Use these options with care.

    -S OPTS, --sphinx-opts=OPTS
                        pass comma-separated OPTS to sphinx-build
    -U, --update-mtimes
                        before building reference manual, update modification
                        times for auto-generated ReST files
    -k, --keep-going    Do not abort on errors but continue as much as
                        possible after an error

Change History (13)

comment:1 Changed 6 years ago by nthiery

  • Authors set to Volker Braun
  • Component changed from PLEASE CHANGE to documentation
  • Reviewers set to Nicolas M. Thiéry
  • Type changed from PLEASE CHANGE to enhancement

comment:2 Changed 6 years ago by vbraun

  • Branch set to u/vbraun/keep_going_in_doc_errors

comment:3 Changed 6 years ago by vbraun

  • Commit set to 0e912bff9562e40c44963c9549dc1a48a5554293
  • Description modified (diff)
  • Status changed from new to needs_review

New commits:

0e912bfAdd sage -docbuild -k option to keep going after errors

comment:4 Changed 6 years ago by vbraun

  • Cc ncohen added
  • Keywords days57 added

comment:5 Changed 6 years ago by ncohen

AHahahah. Thank you Volker :-D

comment:6 Changed 6 years ago by ncohen

HMmmmmmm... I try to read and understand how it works, but it does not work for my own use yet. The "raise OSError" which is called when there is a broken link in a page is in custom-sphinx-build.py.

I added a commit for that in public/16100. Is that okay for you ? If it is I will look again at your commit and review it properly, i.e. try to understand it :-P

Nathann

comment:7 Changed 6 years ago by nthiery

Yup, Volker is working on that right now :-)

comment:8 Changed 6 years ago by ncohen

Well, short of this I agree with the commit. The only thing is that the "if ABORT_ON_ERROR:" added before the raise makes me wonder if anything is displayed when the exception is caught. Not having the exception is cool, thinking that nothing happened is something different :-P

And I do not know how to test that.

Unfortunately I have to leave right now, and I may not be near a computer for the next few days...

Thank you very much again, Volker ! I want to keep the links working, and this really helps to track them :-)

Nathann

comment:9 Changed 6 years ago by git

  • Commit changed from 0e912bff9562e40c44963c9549dc1a48a5554293 to d51fa29ccb34691959a99f967c17e0a2999130b2

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

d51fa29when aborting wait until the end of the source file

comment:10 Changed 6 years ago by vbraun

  • Cc ​jhpalmieri added

The actual error message consists of three lines and looks like

[geometry ] <autodoc>:0: ERROR: Unknown directive type "blah".
[geometry ] .. blah::
[geometry ] /home/vbraun/Code/sage/local/lib/python2.7/site-packages/sage/geometry/cone.py:docstring of sage.geometry.cone:0: ERROR: Unknown directive type "foo".

If we raise the error on the first error line then we lose the important information about the file that contains the error. The updated patch will spit out all error messages in the file before aborting (or not abort if you pass -k).

comment:11 Changed 6 years ago by git

  • Commit changed from d51fa29ccb34691959a99f967c17e0a2999130b2 to 1e7bc36e6ecda3e167bb12b1b78c87dc41b8fa82

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

1e7bc36only print backtrace once

comment:12 Changed 6 years ago by vbraun

  • Status changed from needs_review to positive_review

Nicolas reviewed the ticket

comment:13 Changed 6 years ago by vbraun

  • Branch changed from u/vbraun/keep_going_in_doc_errors to 1e7bc36e6ecda3e167bb12b1b78c87dc41b8fa82
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.