
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. 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.


Block Directives
================

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:


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.

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.


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 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:
