[Twisted-Python] lore2sphinx themeing

Kevin Horn kevin.horn at gmail.com
Tue Jan 5 00:36:13 EST 2010

On Mon, Jan 4, 2010 at 8:46 PM, Glyph Lefkowitz <glyph at twistedmatrix.com>wrote:

> On Jan 4, 2010, at 7:18 PM, Kevin Horn wrote:
> > Thanks to a quick patch from Michael Thompson, the current output of the
> Sphinx conversion [1] now matches the color scheme and typographic style of
> the main twisted site.  It's using the layout of the 'default' sphinx theme
> (previously was using the 'sphinxdoc' theme).
> This is an improvement, but it looks like a very rough cut to me.

Like I said, this is the default sphinx theme with some different colors and
text styling.  Yes, very rough.

> The link colors are wrong, it's missing the subtle top/bottom gradients,
> there's no Twisted logo anywhere, etc etc.

I'm not sure I understand what you mean about the link colors being
wrong...unless you mean the hover/active/visited colors?  The colors for
links both in the text and in the navigation areas are identical to that in

Logo, gradients, etc. were put off until there was a clear understanding of
what exactly was desired.

Spihnx has three "levels" of theme customization.
1. theme options - themes can be set up to take options, which are basically
configurable variables in the templates and css.  This is what's been done
so far.  Just set some colors and fonts.
2. user templates/static files - here you can override templates from the
theme you are using and put things like your own image files, javascript,
css, etc.
3. user themes - a directory or zip file of user templates and static files,
basically as (2), except packaged up nicely to be reusable.

> > I'd like to know what people out there want/expect the final theme of the
> Sphinx version of the Twisted docs to look like.
> Well, if it ended up looking more or less like it does now, but with a bit
> more attention to detail (at a minimum: some gradients, matching colors, a
> little global navigation to get you back to some Trac pages) I'd be happy,
> and it would be an upgrade.
> However, ideally, the page would include links to <
> http://twistedmatrix.com/trac/chrome/common/css/trac.css> and <
> http://twistedmatrix.com/trac/chrome/common/css/wiki.css>, and use the CSS
> classes defined there in its own HTML templates.
> While this isn't the cleanest CSS in the world, using it would have two
> significant benefits:
>  1. lots of little details, like fonts, colors, sizes, etc, which would be
> exhausting for anyone to investigate and enumerate completely, would line up
> correctly and make it look more polished, and
>  2. if we changed the CSS to adjust the look of the trac site, the docs
> would adjust with it.
> I don't mind if this means that some HTML needs to be copied and pasted
> directly from either Trac's templates or Trac's output, as long as it is a
> quick 2-minute cut/paste/edit job that can be quickly explained in a comment
> for someone wanting to update it to a new theme.  I'd much rather have a
> still-slightly-inconsistent documentation theme than burn weeks copy/pasting
> hundreds of little things out of the trac HTML and pain-stakingly
> re-creating every minor effect on the Trac site.
Groovy, this is exactly the kind of feedback I was looking for.

As far as the CSS goes, I think the best way to handle this would be to
create a stylesheet for the theme, that uses @import to pull in the trac.css
and wiki.css files, and the add or override whatever is necessary.
Templates might be a bit harder to reuse, but we still might be able to do

Thanks for all the good work!
It's like an addiction. :)

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20100104/b2644a50/attachment.htm 

More information about the Twisted-Python mailing list