[Twisted-Python] Questions about adding documentation

Jean-Paul Calderone exarkun at divmod.com
Thu Jul 30 23:35:35 EDT 2009


On Thu, 30 Jul 2009 20:49:54 -0400, Jessica McKellar <jessica.mckellar at gmail.com> wrote:
>Hi everyone,
>
>I would like to help Twisted by adding documentation or reviewing existing
>documentation. However, I don't see many (any?) unassigned tickets regarding
>documentation of specific items, and because I am quite new to Twisted this
>makes it hard for me to determine where you wish I would focus my attention.

Hi Jessica,

First let me say hooray. :)  Any attention you can direct at any of Twisted's
documentation will be much appreciated. :)

Don't worry about trying to find an unassigned ticket.  We try to keep all
tickets assigned to someone.  That doesn't mean the person is actively
working on resolving the ticket, just that at some point in time, someone
felt like that assignee should have responsibility for it.  You may want to
comment on a ticket before starting to work on it, asking if anyone is
really working on it, or if there is any work which has been started which
you can pick up.  However, for most tickets, you'll very likely find answers
in the negative for both these questions.

>
>Where should I focus my attention? Want to open some tickets for me to
>claim? Is adding to API docs more important than updating the examples and
>howtos?

Either API doc work or howto work will be appreciated.  I find that the API
docs are in better shape overall (except for a few dark corners), so I would
probably recommend focusing on howtos (and perhaps examples).

Here are a few tickets in particular which I think it would be worthwhile to
resolve:

    http://twistedmatrix.com/trac/ticket/1136
    http://twistedmatrix.com/trac/ticket/1627
    http://twistedmatrix.com/trac/ticket/3784
    http://twistedmatrix.com/trac/ticket/3835

    

>It looks like to add to the API docs you just update the doc strings for
>functions and let someone let pydoctor do its magic later. Is that true? Is
>there a special Twisted pydoctor incant to see how they'd look on the web
>before doing any hasty patch-submitting?

Yep, that's right.  There's just a little specialness involved in the
pydoctor invocation.  Here's a decent command line to use:

    pydoctor --quiet --make-html --system-class \
        pydoctor.twistedmodel.TwistedSystem --add-package twisted

where the final "twisted" is the path to the "twisted" directory beneath a
Twisted checkout (ie, the path which has as a sibling the "doc" directory,
the "README" file, etc).

Make sure you have epydoc installed or pydoctor will give you unpleasant
looking results with unparsed epytext strings in it.

There are two other areas in which I think documentation work would yield a
great benefit.  First, in general editing for readability, coherency, and
general ease of understandability of any of the existing documents.  These
are often rough first drafts which no one was interested in polishing, or
rough first drafts which have had dozens of minor edits by multiple authors
with little concern for the overall document flow.

Second, in a comprehensive high-level overview of what documentation is
missing, what documentation exists, and how it all fits together.  The
output of this would be recommendations about what new documentation to
write, what old documentation to scrape, what documents could be merged,
more closely linked, or otherwise made to cooperate to provide easier
access to the information they present.  This is probably a big task, and
one which requires familiarity with a lot of Twisted.  I'm not sure how
much Twisted experience you already have, but I wanted to mention it in
case it sounds like something you'd be interested in.

Finally, a couple years ago an attempt was made to seriously do something
about the state of the documentation.  It didn't get far enough to produce
actual changes to the documentation, but it did produce some output.  This
may be useful.  You can find it on the wiki:

  http://twistedmatrix.com/trac/wiki/DocumentationAnalysis

>
>I'd like to update
>http://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs to include some
>of this information as well as help I got earlier for updating xhtml
>documentation.

That sounds like a great idea.  Wiki pages require a special permission to
be set on your trac user.  If you let me know what your username is, I can
take care of adding that for you.

Thanks!

Jean-Paul



More information about the Twisted-Python mailing list