[Twisted-Python] prerelease preview predocumentation

Kevin Horn kevin.horn at gmail.com
Mon Mar 28 14:39:05 EDT 2011


On Mon, Mar 28, 2011 at 10:14 AM, George Pauly
<george at ringdevelopment.com>wrote:

>
> On Sun, Mar 27, 2011 at 8:57 PM, Glyph Lefkowitz
> <glyph at twistedmatrix.com> wrote:
> >
> >         On Mar 23, 2011, at 9:34 PM, Glyph Lefkowitz wrote:
> >
> >         > <http://twistedmatrix.com/~glyph/sphinx-preview-11.0pre1/>
> >
> >
> >         Anyone have comments about this?  With all the recent
> >         excitement about the docs, I thought there would be a much
> >         more active thread here!
> >
>
> Looks great, the world needs this.
>
>
> To make it even better:
>
> Search caption ("Quick Search") should be "Search TwistedMatrix.com" or
> "Search Twisted Documentation" or whatever the search space is/will be.
>

Noted.  This is a good idea.


> The different amounts of detail and subdivisions among TOC topics are a
> little clumsy with the heirarchical UI.  For example, Twisted IM
> Documentation seems to have an extra layer of indirection.  Would an
> expando menu of some sort be possible?  It seems a little rough to go
> through a series of menu pages.
>

I'm not sure exactly what you mean here.  I agree that the naming of
documents is a bit confusing, and intend to address that following the
actual conversion.  This has to do with the fact that in some places Sphinx
is picking up the actual name of the document, and in other places it's
picking up the link text from what was previously an <a> tag in the Lore
sources.  Also some documents are just poorly named or have outdated names.
(e.g. Twisted IM rather than Twisted Words).

Can you clarify what you meant by "an extra layer of indirection?"

I think an "expando" menu is a bad idea, assuming I understand what you mean
here.  Or rather, I think that there are some structural issues which need
to be solved, and an "expando" menu wouldn't solve them.


> "This Page / Show Source" (on rhs menu) could be confusing in context
> (it's not the Twisted source).  Is this for Sphinx debugging?   It
> doesn't seem useful to someone seeking Twisted docs.
>

This is easily removed with a config setting in the Sphinx config file,
though I find it helpful when writing docs.  Most Sphinx sites seem to leave
it in, though if others find it confusing we can remove it.

Alternatively, perhaps we could just change the link text to clarify it a
bit. Something like "show Sphinx source?" "Show ReST source?"


> Should Lore docs be removed from the menu? - this will be confusing.
>

The Lore docs will disappear when the Lore docs (and Lore itself) are
removed from trunk.


> "index" link goes to empty page
>

The index is generated by default mostly from docstrings.  Twisted is not
currently using Sphinx's docstring utilities, as all of Twisted's docstrings
use epydoc markup, rather than Restructured Text.

There are several ways we can go with this, but I consider it low priority,
since the current docs have nothing like an index at present.


> >
> >         Thoughts about whether we should link it from the front page?
> >
> >
>
> Definitely link it.
>
>
> hth,
>
> George
> --
> George Pauly
> Ring Development
> www.ringdevelopment.com
>
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110328/ef0050f8/attachment-0001.htm 


More information about the Twisted-Python mailing list