[Twisted-Python] Using SerialPort with t.a.s.Application

[Kevin Horn]

On Sun, Jan 30, 2011 at 2:22 AM, Glyph Lefkowitz <glyph at twistedmatrix.com>wrote:

> On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <andrew at bemusement.org>
> wrote:
>
> > Glyph Lefkowitz wrote:
> > [...]
> >>   The whole idea of a glossary concerns me a little bit.  …  However,
> Twisted
> >>   does have its own jargon and a dictionary to help the novice parse it
> would
> >>   be a good thing.
> >>   What I'd really like to see in this regard is to make sure that every
> >>   "jargon term" is linked straight to API documentation
> >
> > We already have a glossary:
> >
> > <http://twistedmatrix.com/documents/current/core/howto/glossary.html>
>
> Yeah, that came up a bit later in the thread :).  And kevin did mention
> that maintaining that doc is the first order of business.
>
> > And for what it's worth, it's entry for Service is:
> >
> >    A twisted.application.service.Service [link to API doc]. See
> >    Application howto [link] for a description of how they relate to
> >    Applications [glossary link].
> >
> > Superficially, this would appear to satisfy both you and Kevin: there is
> > a glossary, and it is very explicit (at least in this entry) that the
> > API doc is the canonical reference.
> >
> > So whatever it is you're both asking for you perhaps both need to be
> > clearer about what it is :)
>
> I think that the fact such a discussion was able to go on for so long
> before we discovered it really just emphasizes another thing that comes up
> very frequently in these discussions: discoverability of the documentation.
>  We need more and better links to such things.
>
>
Well, first off, I did know about the glossary.  It's dismal state is one of
the things that motivated me to start working on Twisted Documentation.  As
I mentioned in the other thread, a glossary is one of the first things I
look for in a documentation set.

Secondly, Twisted actually has 2 glossaries.  One general one (referenced
above) and one specific to Twisted Web (here:
http://twistedmatrix.com/documents/current/web/howto/glossary.html).  It
has, however, only one entry.  I intend in future to combine the two, unless
someone else does it first.

Thirdly, as far as discoverability/navigability of the documentation, I
think Sphinx (*) will help a lot here.  It has all kinds of tools to make
cross-linking as easy as possible, like the toc segments in the sidebar,
prev/next links, glossary links, indexing, etc.

Should help quite a bit, I think.

Kevin Horn

(*)  I know, I _know_!  I'm working on it! :)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110130/5e669222/attachment-0001.html>