Bug 960969 - Write documentation style guide. r=LpSolit, a=justdave.

docs/en/rst/style.rst

+:orphan:
+
+==============================
+Writing Bugzilla Documentation
+==============================
+
+The Bugzilla documentation uses
+`reStructured Text (reST) <http://docutils.sourceforge.net/rst.html>`_,
+as extended by our documentation compilation tool,
+`Sphinx <http://sphinx-doc.org/>`_. 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 <http://sphinx-doc.org/latest/rest.html>`_
+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 <http://sphinx-doc.org/latest/markup/inline.html>`_
+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:
+
+.. _uniqueanchorname:
+
+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: :ref:`uniqueanchorname`. 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:
+
+.. This is a comment. It can go on to multiple lines. Follow-on lines need to
+   be indented.
+
+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:
+
+.. highlight:: console
+
+You can change the highlighter for a particular block by introducing it like
+this:
+
+.. code-block:: perl
+
+  # This is some Perl code
+  print "Hello";
+
+There is a
+`list of all available lexer names <http://pygments.org/docs/lexers/>`_
+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:
+:file:`/path/to/filename.ext`
+
+A command to type in the shell is displayed like this:
+:command:`command --arguments`
+
+We place static values for substitution (using |subst-name|) in the file
+: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:
+
+.. |subst-name| replace:: Some Text Here