1 How to write sparse documentation
   2 =================================
   3 
   4 Introduction
   5 ------------
   6 
   7 
   8 The documentation for Sparse is written in plain text augmented with
   9 either `reStructuredText`_ (.rst) or `MarkDown`_ (.md) markup. These
  10 files can be organized hierarchically, allowing a good structuring
  11 of the documentation.
  12 Sparse uses `Sphinx`_ to format this documentation in several formats,
  13 like HTML or PDF.
  14 
  15 All documentation related files are in the ``Documentation/`` directory.
  16 In this directory you can use ``make html`` or ``make man`` to generate
  17 the documentation in HTML or manpage format. The generated files can then
  18 be found in the ``build/`` sub-directory.
  19 
  20 The root of the documentation is the file ``index.rst`` which mainly
  21 lists the names of the files with real documentation.
  22 
  23 .. _Sphinx: http://www.sphinx-doc.org/
  24 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  25 .. _MarkDown: https://en.wikipedia.org/wiki/Markdown
  26 
  27 
  28 .. _rest-markup:
  29 
  30 Minimal reST cheatsheet
  31 -----------------------
  32 
  33 Basic inline markup is:
  34 
  35 * ``*italic*`` gives *italic*
  36 * ``**bold**`` gives **bold**
  37 * ````mono```` gives ``mono``
  38 
  39 Headings are created by underlining the title with a punctuation
  40 character; it can also be optionally overlined::
  41 
  42         #############
  43         Major heading
  44         #############
  45 
  46         Minor heading
  47         -------------
  48 
  49 Any punctuation character can be used and the levels are automatically
  50 determined from their nesting. However, the convention is to use:
  51 
  52 * ``#`` with overline for parts
  53 * ``*`` with overline for chapters
  54 * ``=`` for sections
  55 * ``-`` for subsections
  56 * ``^`` for subsubsections
  57 
  58 
  59 Lists can be created like this::
  60 
  61         * this is a bulleted list
  62         * with the second item
  63           on two lines
  64         * nested lists are supported
  65 
  66                 * subitem
  67                 * another subitem
  68 
  69         * and here is the fourth item
  70 
  71         #. this is an auto-numbered list
  72         #. with two items
  73 
  74         1. this is an explicitly numbered list
  75         2. with two items
  76 
  77 
  78 Definition lists are created with a simple indentation, like::
  79 
  80         term, concept, whatever
  81                 Definition, must be indented and
  82                 continue here.
  83 
  84                 It can also have several paragraphs.
  85 
  86 Literal blocks are introduced with ``::``, either at the end of the
  87 preceding paragraph or on its own line, and indented text::
  88 
  89         This is a paragraph introducing a literal block::
  90 
  91                 This is the literal block.
  92                 It can span several lines.
  93 
  94                 It can also consist of several paragraphs.
  95 
  96 Code examples with syntax highlighting use the *code-block* directive.
  97 For example::
  98 
  99         .. code-block:: c
 100 
 101                 int foo(int a)
 102                 {
 103                         return a + 1;
 104                 }
 105 
 106 will give:
 107 
 108 .. code-block:: c
 109 
 110         int foo(int a)
 111         {
 112                 return a + 1;
 113         }
 114 
 115 
 116 Autodoc
 117 -------
 118 
 119 .. highlight:: none
 120 .. c:autodoc:: Documentation/sphinx/cdoc.py
 121 
 122 For example, a doc-block like::
 123 
 124         ///
 125         // increment a value
 126         //
 127         // @val: the value to increment
 128         // @return: the incremented value
 129         //
 130         // This function is to be used to increment a
 131         // value.
 132         //
 133         // It's strongly encouraged to use this
 134         // function instead of open coding a simple
 135         // ``++``.
 136         int inc(int val)
 137 
 138 will be displayed like this:
 139 
 140 .. c:function:: int inc(int val)
 141         :noindex:
 142 
 143         :param val: the value to increment
 144         :return: the incremented value
 145 
 146         This function is to be used to increment a
 147         value.
 148 
 149         It's strongly encouraged to use this
 150         function instead of open coding a simple
 151         ``++``.
 152 
 153 Intermediate Representation
 154 ---------------------------
 155 .. c:autodoc:: Documentation/sphinx/ir.py