Opened 7 years ago

Closed 7 years ago

#2925 enhancement closed fixed (fixed)

Need first-class release documentation generation code

Reported by: radix Owned by:
Priority: normal Milestone: twisted-8.0
Component: release management Keywords:
Cc: Branch: branches/generate-release-docs-2925
(diff, github, buildbot, log)
Author: radix Launchpad Bug:

Description

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.

Change History (10)

comment:1 Changed 7 years ago by radix

  • author set to radix
  • Branch set to branches/generate-release-docs-2925

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

comment:2 Changed 7 years ago by 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.

comment:3 Changed 7 years ago by radix

  • Keywords review added
  • Owner radix deleted

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.

comment:4 Changed 7 years ago by exarkun

  • Owner set to exarkun
  • Status changed from new to assigned

comment:5 Changed 7 years ago by exarkun

  • Keywords review removed
  • Owner changed from exarkun to radix
  • Status changed from assigned to new
  • Summary changed from Need first-class release documentation generation code to z
  • 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

comment:6 Changed 7 years ago by exarkun

  • Summary changed from z to Need first-class release documentation generation code

comment:7 Changed 7 years ago by radix

  • Keywords review added
  • Owner changed from radix to exarkun

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.

comment:8 Changed 7 years ago by exarkun

  • Keywords review removed
  • Owner changed from exarkun to radix

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.

comment:9 Changed 7 years ago by radix

  • Resolution set to fixed
  • Status changed from new to closed

(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.

comment:10 Changed 4 years ago by <automation>

  • Owner radix deleted
Note: See TracTickets for help on using tickets.