Writing Bugzilla Documentation¶
The Bugzilla documentation uses reStructured Text (reST), as extended by our documentation compilation tool, Sphinx. This document is a reST document for demonstration purposes. To learn from it, you need to read it in reST form.
When you build the docs, this document gets built (at least in the HTML version) as a standalone file, although it isn't as useful 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:
Block Directives¶
Chapter headings use the double-equals, page title headings the #, and then the three other levels are headings within a page. Every heading should be preceded by an anchor, with a globally-unique name with no spaces. Now, we demonstrate the available heading levels we haven't used yet:
Third Level Heading¶
Fourth Level Heading¶
Fifth Level Heading¶
(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.
Todo
This is some documentation-related task that still needs doing. This is useful for short-term todos during development; however, consider filing a bug for todos which will persist longer.
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.
Use 4-space indentation, except where a different value is better so that things line up. So normally two spaces for bulleted lists, and 3 spaces for .. blocks.
Inline Directives¶
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: /path/to/variable-bit-of-path/filename.ext
- A command to type in the shell: command --arguments
- A parameter name: shutdownhtml
- A parameter value: DB
- A group name: editbugs
- A bug field name: Summary
- Any string from the UI: Administration
- A specific BMO bug: bug 201069
This documentation undoubtedly has bugs; if you find some, please file them here.
