1How to write sparse documentation
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	: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
153Intermediate Representation
154---------------------------
155.. c:autodoc:: Documentation/sphinx/ir.py
156