1Documentation guide 2=================== 3 4Introduction 5------------ 6 7 8The documentation for Sparse is written in plain text augmented with 9either `reStructuredText`_ (.rst) or `MarkDown`_ (.md) markup. These 10files can be organized hierarchically, allowing a good structuring 11of the documentation. 12Sparse uses `Sphinx`_ to format this documentation in several formats, 13like HTML or PDF. 14 15All documentation related files are in the ``Documentation/`` directory. 16In this directory you can use ``make html`` or ``make man`` to generate 17the documentation in HTML or manpage format. The generated files can then 18be found in the ``build/`` sub-directory. 19 20The root of the documentation is the file ``index.rst`` which mainly 21lists 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 30Minimal reST cheatsheet 31----------------------- 32 33Basic inline markup is: 34 35* ``*italic*`` gives *italic* 36* ``**bold**`` gives **bold** 37* ````mono```` gives ``mono`` 38 39Headings are created by underlining the title with a punctuation 40character; it can also be optionally overlined:: 41 42 ############# 43 Major heading 44 ############# 45 46 Minor heading 47 ------------- 48 49Any punctuation character can be used and the levels are automatically 50determined 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 59Lists 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 78Definition 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 86Literal blocks are introduced with ``::``, either at the end of the 87preceding 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 96Code examples with syntax highlighting use the *code-block* directive. 97For example:: 98 99 .. code-block:: c 100 101 int foo(int a) 102 { 103 return a + 1; 104 } 105 106will give: 107 108.. code-block:: c 109 110 int foo(int a) 111 { 112 return a + 1; 113 } 114 115 116Autodoc 117------- 118 119.. highlight:: none 120.. c:autodoc:: Documentation/sphinx/cdoc.py 121 122For 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 138will 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 153Intermediate Representation 154--------------------------- 155.. c:autodoc:: Documentation/sphinx/ir.py 156