make it easy for someone to generate and view the narrative documentation
|Reported by:||Glyph||Owned by:|
Description (last modified by )
If someone sits down and wants to contribute narrative documentation to Twisted, it should be very quick to do that.
Let me use this ticket as a reminder that if you want to contribute documentation to Twisted, you may do it in any format and we will translate it for you. You don't need to write Lore. Writing Lore is easier than you might think, but we are quite happy to translate your work into our format and you should not think for even one more second about not writing docs for Twisted because you can't get into our toolchain. Stop reading this ticket description and go write some docs. Come back when you're done.
Already wrote a document and submitted it? Okay.
With the above in mind, it's actually really easy to write lore (it's just HTML) and really easy to generate it, except for the fact that at some point during the much-maligned effort to split up Twisted into multiple pieces, some things got moved around and you had to start doing this:
$ cd doc $ ../bin/lore/lore --config template=core/howto/template.tpl [path/to/my/document.xhtml]
instead of simply this, as when I originally wrote lore:
$ cd doc $ ../bin/lore [path/to/my/document.xhtml]
If you arrived at this ticket because you just want to write some lore, just make the above example a shell alias or something and don't worry about it. Go write another document now, and submit it. Come back when you're done.
(Are the new viewers gone yet?)
The most unfortunate thing about the above command line is that the
--config option is totally undocumented and there's no way to guess that
template= is the thing you need to pass, or where the template actually is.
However, it would be nice for 'lore' to just be the only thing you need to type in the doc directory in order to generate all the docs so you can read them.
This can be fixed by simply doing:
Twisted/trunk$ svn mv doc/core/howto/template.tpl doc/template.tpl
So I am filing this ticket mostly in order to do the work necessary to verify that this does not break anything about release automation, or any of the buildbots.