Documentation/doc-guide.rst

   1 Documentation guide
   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         :noindexentry:
 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