Themes

Because not everyone wants their documentation to look the same, RockChisel has a themeing engine.

Themeing is fairly open ended, and you are not required to keep the left-hand sidebar or follow any conventions.

The theme we ship with is rockchisel.themes.rockdoc, which observant readers may notice is a Python package!

You do not have to use themes that come with RockChisel, but themes should be discoverable through the PYTHON_PATH environment setting if not.

Using A Theme

Both the theme selection and theme specific options are defined in a project's site.py.
#!/usr/bin/python


site = Builder(

    # ...

	theme = "rockchisel.themes.rockdoc",

	# ...

	theme_options = dict(
	    sidebar_background = "#FF0000"
	)

)

site.build()
theme_options (added in version 0.2) are unique to each theme. The examples above are options for the rockdoc theme.

Creating Your Own Theme

First, read the source to the rockdoc theme. Rockdoc is the default theme for Rock Chisel, and all user themes should follow the same patterns and rules as this one.

__init__.py

Each theme file must have some common settings in __init__.py. This is fairly short:
THEME_META = dict(
	author = "Michael DeHaan",
	email = "michael@michaeldehaan.net",
	license = "MIT",
	url = "http://rockchisel.com",
	version = "0.1"
)

VARIABLES = dict(
	foo = 'bar',
	baz = 123
)

SNIPPETS = [
	'footer', 'header', 'topleft'
]

MACROS = [
	'macros', 'user_macros'
]

The THEME_META contains information about the theme that is currently not processed by anything.

VARIABLES sets some quick template variables that are available in all user templates, but most themes won't need to define any.

SNIPPETS is important to understand. It defines what small parts of theme can be overridden by users by dropping a file of the same name in their project input directory. Header and footer are largely obvious. 'topleft' corresponds to the top left corner of the system and is a good place to drop in a logo. If you are writing your own theme, you can choose to use more snippets than this, but we recommend studying rockdoc's theme code for reference.

Finally, MACROS defines files that declare Jinja2 macros the user can use. These are used to provide such features as syntax highlighting. RockChisel actually provides non-theme implementations of these, but the theme can, if it wants, choose to override the ones that come with RockChisel or provide new ones. The macro file 'user_macros' should not be set by theme, and is reserved for project directories to define their own macros that can be used in every template.

Files and Templates

The main file that every documentation page in a Rock Chisel project is rendered against is theme.j2. As mentioned above, it may be built out of numerous SNIPPETS, that the user can override in their project files - effectively substituting out small components of the theme. These are the SNIPPETS defined in the __init__.py for the theme.

Any CSS file in the theme directory is also treated as a Jinja2 template (since version 0.2). It has access to theme_options but not other project variables.

The theme directory can also contain static files like images or javascript, and these are copied over directly without any templating applied.