Need first-class release documentation generation code

[radix]

admin/process-docs and the lore-calling code in admin/release-twisted are both nightmares. Let's do something TDD which generates our documentation for release in a non-sucky way.

[radix]

(In [21957]) Branching to 'generate-release-docs-2925'

[radix]

Status update: It's got pretty much the basic "lore" functionality that release-twisted has, but it still needs to do the rest of the stuff that admin/process-docs does, like generating man page HTML and generating the book.

[radix]

Ok, I guess this can be reviewed, maybe.

It doesn't generate book stuff; it only does what's necessary to facilitate the tarball building so far. I've created other tickets (#2940, #2941) for that stuff.

[exarkun]

• twisted/python/test/test_release.py
  • import section uses backslash line continuations against the coding standard
  • @ivars in DocBuilderTestCase.setUp are weird - what does pydoctor do with these?
  • lore_docs doesn't follow naming convention
  • The two-pass interpolation in getArbitraryLoreInput is a bit more confusing than the equivalent single pass implementation would be. Any particular reason you did it this way?
  • These byte-exact xhtml tests are going to hurt for future lore maintenance. I don't have a suggestion for another way to do this, though. Maybe a comment or something pointing out that the exact bytes aren't really important, just the fact that lore ends up doing the right kind of processing.
• twisted/python/_release.py
  • DocBuilder.build has a local input_files which doesn't follow the naming convention
  • Why nest the lore input inside DocBuilder.build?
  • link generation (ie, the 4 lines after the --linkrel comment) could be a separate method and have unit tests. This might not remove the need for any of the byte-exact xhtml assertions in the test module, but it would at least allow lore-independent unit tests for that logic.
  • filePathDelta's arguments would seem to be better named origin and destination.
  • list.extend is a nice method. So is list.__add__, even. Can you use one of those instead of list.__iadd__ at the end of filePathDelta?
• twisted/python/dist.py
  • FilePath imported but unused
• twisted/python/test/test_dist.py
  • three new blank lines at the end of the file, not sure if that was intentional or not

[radix]

Ok, I've dealt with everything. Your questions are now answered:

• import of lore moved to top of module, comment added
• As we discussed on IRC, @ivar in a method documents the instance variables in that method.
• the two-pass interpolation was for a use case that is no longer. I've got rid of the 'body' parameter entirely.
• I've added a maintainer's note to the class docstring for the tests, explaining the byte-equality tests.

[exarkun]

Attribute the lore import comment in _release.py so people can resolve "me" to someone who isn't them. Everything else seems great, no need for re-review.

[radix]

(In [22169]) Merge generate-release-docs-2925

Author: therve,radix Reviewer: exarkun Fixes #2925

A DocBuilder object is added to twisted.python._release which offers convenience for building directories full of documentation with lore.

The functionality included is equivalent with the lore-building code in admin/release-twisted.