[Pywikipedia-bugs] [Maniphest] [Created] T112488: jenkins doc generation rule should vote against changes which create sphinx errors

[jayvdb]

jayvdb created this task.
jayvdb added a subscriber: jayvdb.
jayvdb added a project: Pywikibot-documentation.
Herald added subscribers: pywikibot-bugs-list, Aklapper.
Herald added a project: Documentation.

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

TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: jayvdb
Cc: Aklapper, pywikibot-bugs-list, jayvdb, Spage

[Legoktm]

Legoktm added a subscriber: Legoktm.
Legoktm added a comment.

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


TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: Legoktm
Cc: Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Spage

[jayvdb]

jayvdb added a comment.

Post by Legoktm
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.
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 <https://phabricator.wikimedia.org/T74424>.

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


TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: jayvdb
Cc: Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Spage

[jayvdb]

jayvdb added a comment.

Reported https://phabricator.wikimedia.org/tag/upstream/ as https://github.com/sphinx-doc/sphinx/issues/2041


TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: jayvdb
Cc: Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Spage

[jayvdb]

jayvdb added a project: Upstream.

TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: jayvdb
Cc: Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Krenair, Spage

[jayvdb]

jayvdb moved this task to Reported Upstream on the Upstream workboard.

TASK DETAIL
https://phabricator.wikimedia.org/T112488

WORKBOARD
https://phabricator.wikimedia.org/project/board/153/

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: jayvdb
Cc: Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Krenair, Spage

[gerritbot]

gerritbot added a subscriber: gerritbot.
gerritbot added a comment.

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

https://gerrit.wikimedia.org/r/238420


TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: gerritbot
Cc: gerritbot, Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Krenair, Spage

[gerritbot]

gerritbot added a project: Patch-For-Review.

TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: gerritbot
Cc: gerritbot, Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Krenair, Spage

[gerritbot]

gerritbot added a comment.

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

https://gerrit.wikimedia.org/r/238420


TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: gerritbot
Cc: gerritbot, Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Krenair, Spage

[jayvdb]

jayvdb triaged this task as "Low" priority.
jayvdb removed a project: Patch-For-Review.
jayvdb set Security to None.

TASK DETAIL
https://phabricator.wikimedia.org/T112488

EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/

To: jayvdb
Cc: gerritbot, Legoktm, Aklapper, pywikibot-bugs-list, jayvdb, Krenair, Spage

[Dvorapa]

_______________________________________________
pywikibot-bugs mailing list
pywikibot-***@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/pywikibot-bugs

[Dalba]

_______________________________________________
pywikibot-bugs mailing list
pywikibot-***@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/pywikibot-bugs