The Bugzilla documentation uses reStructured Text (reST), as extended by our documentation compilation tool, Sphinx. This document is a reST document for demonstration purposes. When you build the docs, it gets built (at least in the HTML version) as a standalone file, although it isn't as readable in that form because some of the directives discussed are invisible or change when rendered.
The Sphinx documentation gives a good introduction to reST and the Sphinx-specific extensions. Reading that one immediately-linked page should be enough to get started. Later, the inline markup section is worth a read.
Bugzilla's particular documentation conventions are as follows.
Every heading should be preceded by an anchor, with a globally-unique name with no spaces. Then we demonstrate the available heading levels we haven't used yet:
(Although try not to use headings as deep as the 5th level.)
Make links to anchors like this: Third Level Heading. It'll pick up the following heading name automatically and use it as the link text. Don't use standard reST internal links like uniqueanchorname - they don't work across files.
Comments are done like this:
Other block types:
Note
This is just a note, for your information. Like all double-dot blocks, follow-on lines need to be indented.
Warning
This is a warning of a potential serious problem you should be aware of.
Use both of the above block types sparingly. Consider putting the information in the main text, omitting it, or (if long) placing it in a subsidiary file.
Code gets highlighted using Pygments. Choose the highlighter at the top of each file using:
You can change the highlighter for a particular block by introducing it like this:
# This is some Perl code
print "Hello";
There is a list of all available lexer names available. We currently use console, perl, and sql. none is also a valid value.
Warning
Remember that reST does not support nested inline markup. So you can't have a substitution inside a link, or bold inside italics.
A filename or a path to a filename is displayed like this: /path/to/filename.ext
A command to type in the shell is displayed like this: command --arguments
We place static values for substitution (using Some Text Here) in the file $BUGZILLA_HOME/docs/definitions.rst.tmpl. This gets built into definitions.rst, with the script adding some definitions for minimum module versions etc. generated from the source itself. Lines in that file look like this: