TEXT   257

style.txt

Guest on 22nd August 2021 06:49:46 PM

  1. Writing Bugzilla Documentation
  2. ******************************
  3.  
  4. The Bugzilla documentation uses reStructured Text (reST), as extended
  5. by our documentation compilation tool, Sphinx. This document is a reST
  6. document for demonstration purposes. To learn from it, you need to
  7. read it in reST form.
  8.  
  9. When you build the docs, this document gets built (at least in the
  10. HTML version) as a standalone file, although it isn't as useful in
  11. that form because some of the directives discussed are invisible or
  12. change when rendered.
  13.  
  14. The Sphinx documentation gives a good introduction to reST and the
  15. Sphinx-specific extensions. Reading that one immediately-linked page
  16. should be enough to get started. Later, the inline markup section is
  17. worth a read.
  18.  
  19. Bugzilla's particular documentation conventions are as follows:
  20.  
  21.  
  22. Block Directives
  23. ================
  24.  
  25. Chapter headings use the double-equals, page title headings the #, and
  26. then the three other levels are headings within a page. Every heading
  27. should be preceded by an anchor, with a globally-unique name with no
  28. spaces. Now, we demonstrate the available heading levels we haven't
  29. used yet:
  30.  
  31.  
  32. Third Level Heading
  33. -------------------
  34.  
  35.  
  36. Fourth Level Heading
  37. ~~~~~~~~~~~~~~~~~~~~
  38.  
  39.  
  40. Fifth Level Heading
  41. """""""""""""""""""
  42.  
  43. (Although try not to use headings as deep as the 5th level.)
  44.  
  45. Make links to anchors like this: Third Level Heading. It'll pick up
  46. the following heading name automatically and use it as the link text.
  47. Don't use standard reST internal links like uniqueanchorname - they
  48. don't work across files.
  49.  
  50. Comments are done like this:
  51.  
  52. Other block types:
  53.  
  54. Note: This is just a note, for your information. Like all double-dot
  55.   blocks, follow-on lines need to be indented.
  56.  
  57. Warning: This is a warning of a potential serious problem you should
  58.   be aware of.
  59.  
  60. Use both of the above block types sparingly. Consider putting the
  61. information in the main text, omitting it, or (if long) placing it in
  62. a subsidiary file.
  63.  
  64. Code gets highlighted using Pygments. Choose the highlighter at the
  65. top of each file using:
  66.  
  67. You can change the highlighter for a particular block by introducing
  68. it like this:
  69.  
  70.    # This is some Perl code
  71.    print "Hello";
  72.  
  73. There is a list of all available lexer names available. We currently
  74. use "console", "perl", and "sql". "none" is also a valid value.
  75.  
  76. Use 4-space indentation, except where a different value is better so
  77. that things line up. So normally two spaces for bulleted lists, and 3
  78. spaces for .. blocks.
  79.  
  80.  
  81. Inline Directives
  82. =================
  83.  
  84. Warning: Remember that reST does not support nested inline markup.
  85.   So you can't have a substitution inside a link, or bold inside
  86.   italics.
  87.  
  88. * A filename or a path to a filename: "/path/to/*variable-bit-of-
  89.   path*/filename.ext"
  90.  
  91. * A command to type in the shell: **command --arguments**
  92.  
  93. * A parameter name: shutdownhtml
  94.  
  95. * A parameter value: DB
  96.  
  97. * A group name: editbugs
  98.  
  99. * A bug field name: Summary
  100.  
  101. * Any string from the UI: Administration
  102.  
  103. * A specific BMO bug: bug  201069
  104.  
  105. ======================================================================
  106.  
  107. This documentation undoubtedly has bugs; if you find some, please file
  108. them here.

Raw Paste


Login or Register to edit or fork this paste. It's free.