[Twisted-Python] Lore to Sphinx Conversion Progress Report 5

[Kevin Horn]

On Fri, Feb 5, 2010 at 1:00 PM, Terry Jones <terry at jon.es> wrote:

> Hi Kevin
>
> I think this is looking really good. Here are a few superficial / quick
> comments.
>
>  - It looks fine under Google chrome
>

Good to hear!

  - You could reduce visual repetition / density of some of the high-level
>   pages by taking out a word like "Documentation" which appears in the
>   heading and on every line of things like this:
>
>         Twisted Documentation Table of Contents
>            Twisted Conch Documentation
>            Twisted Core Documentation
>            Historical Documents
>            Twisted Lore Documentation
>            Twisted Mail Documentation
>            Twisted Names Documentation
>            Twisted Pair Documentation
>            Twisted VFS Documentation
>            Twisted Web Documentation
>            Twisted Web2 Documentation
>            Twisted Words Documentation
>
>   See also http://twistedsphinx.funsize.net/contents.html which is very
>   cluttered with repeated content.
>
>   I realize these are probably just being picked up out of the .rst header
>   line, and that one of those documents when seen in isolation probably
>   should have a full title. I'm not sure how best to simplify the
>   top-level, though I guess it's possible to extend the sphinx layout.html
>   and override something... may be more trouble than it's worth.
>

A lot of this is because the auto-generated TOC is being shown, and it is
indeed picking up the document titles out of the source file it happens to
be pointing to.  In the final version, I'm thinking we won't really need to
show the toctrees at all, since most of the docs have index files already
(which I'm generating the toctree directives from), so most of this will
"fix itself".


>  - I think it would improve appearance a little to have a non-intrusive
>   border around the green source code boxes.
>

Not a bad idea.  Or maybe an "outline" instead of a "border"?


> I'll see if I can find/make time to have a look at the CSS.
>

That would be really great.  There are a few things that are driving me
bonkers.  For example: the prev/next/index links on the right hand side of
the gray navbar are 1 freakin' pixel lower than the "breadcrumb" links on
the left hand side of the same navbar () at least on this machine), and I
have no idea why.


> Terry
>
> _______________________________________________
> 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/20100205/927a462a/attachment.htm