Page MenuHomePhabricator

jenkins doc generation rule should vote against changes which create sphinx errors
Closed, ResolvedPublic


To prevent new doc problems appearing, a jenkins rule needs to ensure no errors occur doing generation

Event Timeline

jayvdb raised the priority of this task from to Needs Triage.
jayvdb updated the task description. (Show Details)
jayvdb subscribed.
Restricted Application added subscribers: pywikibot-bugs-list, Aklapper. · View Herald Transcript

Do you have an example of a failing change I can test with?

Do you have an example of a failing change I can test with?

Every changeset currently has 'ERROR: ' in the doc job log. e.g.

Here is a changeset where all 'ERROR's are fixed:

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.

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/ --halt=error pywikibot/ _docutils-out/init.html
pywikibot/ (ERROR/3) Unexpected indentation.
Exiting due to level-3 (ERROR) system message.
$ echo $?

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:

halt_level: error

Change 238420 had a related patch set uploaded (by John Vandenberg):
Fail on docutils errors inside Sphinx

Change 238420 merged by jenkins-bot:
Fail on docutils errors inside Sphinx

jayvdb removed a project: Patch-For-Review.
jayvdb set Security to None.
Dalba claimed this task.
Dalba subscribed.

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.