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.
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.
- input_path - this is where to find the templates that will make up your documentation. The code above just
finds it in the same directory as site.py.
- output_path - this is where the documentation project will be rendered. Warning: content here will be erased!
- theme - what theme to use - we ship with one theme called 'rockdoc'. This is discussed later in Themes
- variables - adds any template variables to inject into a template, like a version number or a date
- page_title_template - this is used to render the HTML title tag so the name of the project is in each title.
- sections - this defines the layout of the navigation sidebar. Any template rendered must be in this structure.
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.
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.
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.
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.
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.
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.