Authoring

Writing content in RockChisel is easy, because beyond a basic python definition file, RockChisel is basically HTML. The very best source to understand RockChisel is reading through the source code to the RockChisel documentation itself. First find and read 'site.py', and then browse the templates.

Builder Configuration 

First, let's look at an example configuration file, site.py. The name isn't actually important, but what is interesting is that it is an executable file - this means that RockChisel does not have (or need) a command line tool. Building the project is discussed later in Building.
#!/usr/bin/python

from rockchisel import Builder
import os

path = os.path.dirname(os.path.realpath(__file__))

site = Builder(

	input_path  = path,
	output_path = os.path.join(path, "output"),
	theme = "rockchisel.themes.rockdoc",

	variables = dict(version = 0.1),
	page_title_template = "Rock Chisel {{ version }}: {{ title }}",

	sections = {
			"User Guide": {
				"Home" : "index",
				"Installation": "installation",
				"Authoring": "authoring",
				"Building": "building",
				"Uploading": "uploading",
				"Changelog": "changelog"
			},
			"Community": {
				"License": "license",
				"Contributing": "contributing",
				"Themes": "themes"
			}
	}

)

site.build()
Let's go through some of the settings step by step.

Templates 

As you can see from the RockChisel documentation, the project consists of a number of Jinja2 HTML templates. When writing documentation in RockChisel, you have the full power of HTML, and are not limited by obscure sub-dialects of Restructured Text or Markdown. Variables marked in site.py can be used in templates, as can larger blocks of other files, known as snippets, which we will explain later in this chapter. The easiest way to understand the template system might be to see the source of the previous chapter.

Macros 

Various HTML shortcuts are available, as described in Macros. You do not need to use macros unless you want to, but they can add consistency to your documentation.

Snippets 

Portions of the the theme can be easily replaced without picking a new theme. This feature is discussed in Themes. For instance, the word "RockChisel" in the upper left corner of the documentation is a snippet called "topleft.j2". These are used to make common page headers and footers, or to replace a site logo. Many users will be able to use the stock theme, and we will continue to improve the stock theme over time. If you want to, you may wish to copy the theme to make it your own. The RockDoc theme has three snippets - "topleft.j2", "header.j2", and "footer.j2". Header and footer are essentially plank, and can be used to, for instance, insert copyright messages or tracking codes.

Images and Other Static Files 

If your documentation directory wants to include any graphics or other static files, including custom javascript or CSS, just include them in project directory at the top level, and they will be copied over to the output directory automatically. You can reference them with regular HTML.

File Structure 

Currently all Jinja2 templates should be placed at the top level of your input directory. This isn't extremely flexible, but we suspect it won't matter for most purposes. This could change later.

Next 

With some basic understanding of the system, now it is time to build the docs. Don't forget to skim Macros if you haven't already.