From d41a0a76217ebbfd18807128e8bd552d5276e87a Mon Sep 17 00:00:00 2001 From: Gervase Markham Date: Fri, 5 Dec 2014 16:52:48 -0500 Subject: Bug 1067416 - reorganize and update Bugzilla docs --- docs/en/rst/style.rst | 57 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 18 deletions(-) (limited to 'docs/en/rst/style.rst') diff --git a/docs/en/rst/style.rst b/docs/en/rst/style.rst index 8fd9dc037..aa3957b95 100644 --- a/docs/en/rst/style.rst +++ b/docs/en/rst/style.rst @@ -1,5 +1,7 @@ :orphan: +.. _style-guide: + ============================== Writing Bugzilla Documentation ============================== @@ -8,8 +10,10 @@ 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 +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. @@ -19,14 +23,15 @@ 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. +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: +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: .. _uniqueanchorname: @@ -59,6 +64,8 @@ Other block types: .. warning:: This is a warning of a potential serious problem you should be aware of. +.. todo:: This is some documentation-related task that still needs doing. + 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. @@ -72,30 +79,44 @@ this: .. code-block:: perl - # This is some Perl code - print "Hello"; + # 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 is displayed like this: -:file:`/path/to/filename.ext` +* A filename or a path to a filename: + :file:`/path/to/{variable-bit-of-path}/filename.ext` + +* A command to type in the shell: + :command:`command --arguments` + +* A parameter name: + :param:`shutdownhtml` + +* A parameter value: + :paramval:`DB` + +* A group name: + :group:`editbugs` -A command to type in the shell is displayed like this: -:command:`command --arguments` +* A bug field name: + :field:`Summary` -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: +* Any string from the UI: + :guilabel:`Administration` -.. |subst-name| replace:: Some Text Here +* A specific BMO bug: + :bug:`201069` -- cgit v1.2.3-24-g4f1b