Opened 11 years ago
Closed 11 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
branch-diff, diff-cov, branch-cov, buildbot |
|
Author: | radix |
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 11 years ago by
author: | → radix |
---|---|
Branch: | → branches/generate-release-docs-2925 |
comment:2 Changed 11 years ago by
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 11 years ago by
Keywords: | review added |
---|---|
Owner: | radix deleted |
comment:4 Changed 11 years ago by
Owner: | set to Jean-Paul Calderone |
---|---|
Status: | new → assigned |
comment:5 Changed 11 years ago by
Keywords: | review removed |
---|---|
Owner: | changed from Jean-Paul Calderone to radix |
Status: | assigned → new |
Summary: | Need first-class release documentation generation code → z |
- twisted/python/test/test_release.py
- import section uses backslash line continuations against the coding standard
@ivar
s inDocBuilderTestCase.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 localinput_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 namedorigin
anddestination
.list.extend
is a nice method. So islist.__add__
, even. Can you use one of those instead oflist.__iadd__
at the end offilePathDelta
?
- 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 11 years ago by
Summary: | z → Need first-class release documentation generation code |
---|
comment:7 Changed 11 years ago by
Keywords: | review added |
---|---|
Owner: | changed from radix to Jean-Paul Calderone |
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 11 years ago by
Keywords: | review removed |
---|---|
Owner: | changed from Jean-Paul Calderone 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 11 years ago by
Resolution: | → fixed |
---|---|
Status: | new → 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 8 years ago by
Owner: | radix deleted |
---|
(In [21957]) Branching to 'generate-release-docs-2925'