sphinx :: adding a new theme

Sphinx (http://sphinx.pocoo.org/) has made our internal documentation effort go a lot smoother, and the autodoc extension has provided much needed motivation for writing useful docstrings.

For those unfamiliar with autodoc, a simple declaration in your documentation file:

.. automodule:: test.sphinxtest
   :members:
   :undoc-members:

will automatically document your module, pulling in docstrings automatically:

Sphinx with autodoc output (default theme).

At first glance that’s nice, but after having used it for a while it becomes clear that your eyes are drawn away from the content and onto the “packaging”, like the headers/TOC/etc. It is also difficult to tell which level you’re at since all headers start flush left.

The choice of fonts for describing classes also seems a bit unusual — at least for first time readers:

Sphinx classdef (default theme)

There are other themes to choose from, but if you’re going to customize you might as well create your own theme — especially since it’s really easy.

I’ll use our dktheme as an example, the finished product looks like this:

Sphinx with dktheme

To start, create a folder (dktheme) to hold your theme files. I chose to put it in the documentation folder. Change your conf.py file to reflect the new folder:

html_theme = 'dktheme'
html_theme_path = ['.']

Create a theme.conf file in the folder and provide a few basic configuration settings:

[theme]
inherit = default
stylesheet = dktheme.css
pygments_style = sphinx

inherit declares which theme you want to use as a base (they exist in site-packages/sphinx/themes). pygments_style defines which syntax highlighting color scheme to use.

Create a directory dktheme/static, and put a file named dktheme.css_t in it. Notice the _t suffix. This file corresponds to the stylesheet setting in the dktheme/theme.conf file.

Define your own css rules inside dktheme.css_t, but begin by importing the css file of the theme you’re inheriting from:

@import url("default.css");

Firebug/Webdeveloper/etc. are useful for finding the correct selectors to override:


@import url("default.css");

html, body, h1, h2, h3, h4, h5, h6 {
  font-family: 'Ubuntu', 'Trebuchet MS', sans-serif !important;
}

html,
.bodywrapper,
.documentwrapper,
.footer,
.footer a,
.related,
.related ul,
.related ul li a  {
    background-color: #c0c0cf !important;
    color:#808080 !important;
}

.related ul {
  max-width:900px; margin-left:250px !important; font-size:smaller
}
.related ul a {  background-color: transparent !important;}

.body {
  -moz-box-shadow:0px 0px 12px #666;
  -webkit-box-shadow:0px 0px 12px #666;
  box-shadow:0px 0px 12px #666;
  margin:15px 25px 15px 0px;
  margin:0px 25px 0px 0px;
  border:9px solid white;
  -moz-border-radius:14px;
  -webkit-border-radius:14px;
  border-radius:14px;
  max-width:900px;
}

.sphinxsidebar a,
.sphinxsidebar h3,
.sphinxsidebar h4,
.sphinxsidebar h5 { color:#555 !important }

.sphinxsidebar .searchtip { color:black; }

.body h1,
.body h2,
.body h3,
.body h4,
.body h5,
.body h6 {
  margin-left: 0px !important;
  margin-right: 0px !important;
  padding-left:0 !important;
  background-color: white !important;
}

.body h1 { padding-top:17px !important; }

.section .section { margin-left:14px }

.class big { font-size:85%; }
.class em { font-size:85%; }

.class .property,
.class .descclassname,
.class .descname { font-size:100%; line-height:100%; }

.class .property {
   font-style:normal;
   font-weight:bold;
   color:#1D599F;
}

.descclassname { font-size:100% !important; font-family: Tahoma; }
.descname { color:#041F3F; font-size:100% !important; font-family: Tahoma; }

dl.method::before {
    content:"def";
    float:left; margin-right:0.5ex;
    font-weight:bold; color:#222;
}

dl.attribute::before {
    content:"@property";
    font-size:85%;
    float:left; margin-right:0.5ex;
    font-style:italic;
}

dd > p { font-size:85%; }

I’ve used ::before rules to e.g. insert the word def before method definitions.

At the top I’ve listed the preferred font as being Ubuntu, which is a very clean font that Google has made available as a webfont (www.google.com/webfonts).

To use the Ubuntu web font, you’ll need to add a link to its css file in the <head> section of your html.  To accomplish this, you’ll need to add a final file to your theme, dktheme/layout.html, with the following content:

{% extends "default/layout.html" %}

{% block extrahead %}
<link href="http://fonts.googleapis.com/css?family=Ubuntu:300,300italic,regular,italic,500,500italic,bold,bolditalic" rel="stylesheet" type="text/css">
{% endblock %}

What this does should be obvious to anyone familiar with Django templates (although these are Jinja templates).

I’m not a graphical designer, but to my development eyes the documentation is much easier to use with the new theme :-)

Posted in Uncategorized | Tagged , , | Leave a comment

css :: simple hbox

A hbox is a horizontal box. That means a box where all sub-elements display horizontally across the page, and never wrap.

If you can disregard IE6 (and perhaps IE7… at least IETester doesn’t like it), then a hbox can be as simple as:

  .hbox {
    overflow-x:auto;
  }
  .hbox > * { display:table-cell; }

Then the markup:

  <div class="hbox">
    <div>A</div>
    <div>B</div>
    <div>C</div>
  </div>

Adding some debugging markup to show what’s going on:

  .hbox { border:3px solid green; border-spacing:3px; }
  .hbox > div { border:1px solid blue; padding:5px; }

and you get:

hbox example output

You can use other table-css on the .hbox selector as well, e.g. border-collapse.

Posted in Uncategorized | Leave a comment

new photo frame: pdf to jpg conversion

I got a new digital photo frame for xmas, and it is big enough that I wanted to use it to display the score sheets while I play the piano.  Only problem:  music scores frequently come as pdf files, and the frame only handles simple image files…

ImageMagick to the rescue!

I was doing this on windows, so I first had to download Ghostscript (http://pages.cs.wisc.edu/~ghost/doc/GPL/gpl900.htm).  For some reason I already had ImageMagick installed…. (hmm).

Then the magic incantation:

convert -density 200x200 minuet-g.pdf minuet-g.jpg

ImageMagick automatically splits the pdf into individually numbered .jpg files. The -density argument was necessary to get all the lines to show up.

Posted in Uncategorized | Leave a comment

Welcome to bluehost

I got tired of dealing with GoDaddy after they continued to stone-wall me on the speed issue.  Earlier today I was seeing load times in excess of 40 seconds!

Everything is now switched over to bluehost.com, and hopefully things will converge on normality.  It took a little less than 20 minutes of downtime to do the entire switch, and it could probably have gone even faster if I knew what I was doing.  Big thanks to bluehost for their excellent documentation and for answering their phone almost immediately (no more “your expected wait time is 11 minutes”…!).  Big thanks also to the WordPress team for making it so easy to transfer an entire blog!

Load times are now in a sane range from 328 ms to 1830 ms (the larger numbers are all from Europe).

Posted in Uncategorized | Leave a comment