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

Hi Kevin I think this is looking really good. Here are a few superficial / quick comments. - It looks fine under Google chrome - 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. - I think it would improve appearance a little to have a non-intrusive border around the green source code boxes. I'll see if I can find/make time to have a look at the CSS. Terry

On Fri, Feb 5, 2010 at 1:00 PM, Terry Jones <terry@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@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

On Fri, 5 Feb 2010 13:19:00 -0600 Kevin Horn <kevin.horn@gmail.com> wrote:
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.
After spending a few minutes poking about with Firebug, the reason becomes clear: - In twistedtrac.css line 38, the navbar list items are set to "display: inline", which makes them layout like "<span>" and stack up nicely on the left, but also makes them ignore certain vertical adjustments like margin and padding. - In twistedtrac.css line 42, the navbar list items on the right are set to "float: right", which makes them stack up nicely on the right but also happens to make them respond to margin and padding again. - In trac.css line 179, the navbar list items are set to "padding: 0.25em 0", giving them vertical padding. This is ignored by the inline list items on the left, but respected by the floated list items on the right. I haven't studied the CSS of the main Twisted site, so I don't know how they get around it there. One easy way around it for the docs might be to change "display: inline" to "float: left", which also makes them stack up on the left, and behave consistently with the ones on the right.

On Fri, Feb 5, 2010 at 9:23 PM, Timothy Allen <screwtape@froup.com> wrote:
On Fri, 5 Feb 2010 13:19:00 -0600 Kevin Horn <kevin.horn@gmail.com> wrote:
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.
After spending a few minutes poking about with Firebug, the reason becomes clear:
- In twistedtrac.css line 38, the navbar list items are set to "display: inline", which makes them layout like "<span>" and stack up nicely on the left, but also makes them ignore certain vertical adjustments like margin and padding. - In twistedtrac.css line 42, the navbar list items on the right are set to "float: right", which makes them stack up nicely on the right but also happens to make them respond to margin and padding again. - In trac.css line 179, the navbar list items are set to "padding: 0.25em 0", giving them vertical padding. This is ignored by the inline list items on the left, but respected by the floated list items on the right.
Brilliant! It may only have taken you a few minutes, but it would have taken me...considerably longer. :)
I haven't studied the CSS of the main Twisted site, so I don't know how they get around it there.
On the main twisted site, they don't have anything on the left...not sure how the Sphinx templates handle it though...
One easy way around it for the docs might be to change "display: inline" to "float: left", which also makes them stack up on the left, and behave consistently with the ones on the right.
Actually that jacks up the height on the navbar completely (at least for me). Overriding the padding in twistedtrac.css seems to work though, so I think that's what I'll go with. Thanks for the help! Kevin Horn
participants (3)
-
Kevin Horn
-
Terry Jones
-
Timothy Allen