To prevent new doc problems appearing, a jenkins rule needs to ensure no errors occur doing generation
Description
Description
Details
Details
| Subject | Repo | Branch | Lines +/- | |
|---|---|---|---|---|
| Fail on docutils errors inside Sphinx | pywikibot/core | master | +3 -0 |
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Resolved | Dalba | T112488 jenkins doc generation rule should vote against changes which create sphinx errors | |||
| Resolved | jayvdb | T112491 Fix bugs in Pywikibot doc generation | |||
| Resolved | Xqt | T112830 Sphinx autodoc fails to inspect classes deprecated using ModuleDeprecationWrapper |
Event Timeline
Comment Actions
Every changeset currently has 'ERROR: ' in the doc job log. e.g.
https://integration.wikimedia.org/ci/job/tox-doc-trusty/2667/console
Here is a changeset where all 'ERROR's are fixed:
https://gerrit.wikimedia.org/r/#/c/238039/
https://integration.wikimedia.org/ci/job/tox-doc-trusty/2664/console
I've dug into the Sphinx code, and as far as I can see we have four options:
- also fix every warning, and then enable Sphinx -W
- post process the Sphinx stderr for the word 'ERROR':
- Invoking docutils
- Control the behaviour of docutils within Sphinx using docutils.conf
The problem is that most of our errors are inside docutils, and while they use the word 'ERROR: ' they are treated as a warning inside Sphinx, and the only way to get an error code is to enable -W, but that means all warnings need to be fixed.
See https://github.com/sphinx-doc/sphinx/blob/master/sphinx/application.py#L325
Fixing all warnings is not simple, as those mro warnings means solving the problems of T74424: ModuleDeprecationWrapper breaks code inspection tools, including epydoc, sphinx autodoc.
Invoking docutils with --halt:error does result in an exitcode.
$ /usr/local/bin/rst2html5.py --halt=error pywikibot/__init__.py _docutils-out/init.html pywikibot/__init__.py:34: (ERROR/3) Unexpected indentation. Exiting due to level-3 (ERROR) system message. $ echo $? 1
Running docutils directly isn't a simple option, as we would need to convert epytext to rst before invoking docutils, but it is do-able.
However, we can add a docutils.conf, which can include the following:
[general] halt_level: error
Comment Actions
Change 238420 had a related patch set uploaded (by John Vandenberg):
Fail on docutils errors inside Sphinx
Comment Actions
The upstream issue is closed and we have a patch merged for it. I'm going to close this issue as well as it seem we are not facing this issue anymore.