[Twisted-Python] Pydoctor "ratchet"-style error reporting on BuildBot

[exarkun at twistedmatrix.com]

Hello Twisted developers,

You may have noticed that a little while ago I made a change to the 
documentation builder 
(<http://buildbot.twistedmatrix.com/builders/documentation>).  I changed 
it again today, and I think it now has reasonable behavior, so I thought 
I'd let everyone know what's going on.

One thing the documentation builder does is run pydoctor over Twisted 
and collect errors emitted.  Since avoiding pydoctor errors haven't been 
part of the documented, official development process, we have a lot of 
them - over 500.  The documentation builder hasn't previously reported a 
failure (ie, turned red) because of these, and it still doesn't - quite.

The documentation builder will now report a failure if there are *new* 
pydoctor errors in a build as compared to the most recent trunk build.

So if you add new pydoctor errors to trunk, the build will fail and the 
change must be reverted.

If you build a branch on the documentation builder, it will fail if the 
branch has pydoctor errors that trunk doesn't have.  Use this 
information to fix your documentation changes before submitting the 
branch for review (and certainly before merging it).

You can find a list of pydoctor errors linked from a documentation build 
page (eg 
<http://buildbot.twistedmatrix.com/builders/documentation/builds/1644>). 
Notice step 5, "api-documentation", with a link beneath it, "pydoctor 
errors".

If the builder decides there are new errors, you will also find a "new 
pydoctor errors" link immediately below the "pydoctor errors" link.

Unfortunately there is one shortcoming of the implementation of this 
feature.  If someone else fixes pydoctor errors in trunk and you have a 
branch based on an older build of trunk, those fixed-in-trunk errors 
will be considered new errors in your branch.  You can disregard such 
build failures when you build a branch on the documentation builder.

For anyone who isn't sure how to submit branch build requests to 
buildbot, see <http://labs.twistedmatrix.com/2011/09/pre-trunk- 
testing.html>.

Jean-Paul