[Twisted-Python] lore2sphinx themeing

Glyph Lefkowitz glyph at twistedmatrix.com
Mon Jan 4 21:46:35 EST 2010

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.  The link colors are wrong, it's missing the subtle top/bottom gradients, there's no Twisted logo anywhere, etc etc.  

> 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.

Thanks for all the good work!

More information about the Twisted-Python mailing list