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
12 Sparse uses `Sphinx`_ to format this documentation in several formats,
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.
20 The root of the documentation is the file ``index.rst`` which mainly
21 lists the names of the files with real documentation.
23 .. _Sphinx: http://www.sphinx-doc.org/
24 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
25 .. _MarkDown: https://en.wikipedia.org/wiki/Markdown
30 Minimal reST cheatsheet
31 -----------------------
33 Basic inline markup is:
35 * ``*italic*`` gives *italic*
36 * ``**bold**`` gives **bold**
37 * ````mono```` gives ``mono``
39 Headings are created by underlining the title with a punctuation
40 character; it can also be optionally overlined::
49 Any punctuation character can be used and the levels are automatically
50 determined from their nesting. However, the convention is to use:
52 * ``#`` with overline for parts
53 * ``*`` with overline for chapters
55 * ``-`` for subsections
56 * ``^`` for subsubsections
59 Lists can be created like this::
61 * this is a bulleted list
62 * with the second item
64 * nested lists are supported
69 * and here is the fourth item
71 #. this is an auto-numbered list
74 1. this is an explicitly numbered list
78 Definition lists are created with a simple indentation, like::
80 term, concept, whatever
81 Definition, must be indented and
84 It can also have several paragraphs.
86 Literal blocks are introduced with ``::``, either at the end of the
87 preceding paragraph or on its own line, and indented text::
89 This is a paragraph introducing a literal block::
91 This is the literal block.
92 It can span several lines.
94 It can also consist of several paragraphs.
96 Code examples with syntax highlighting use the *code-block* directive.
120 .. c:autodoc:: Documentation/sphinx/cdoc.py
122 For example, a doc-block like::
127 // @val: the value to increment
128 // @return: the incremented value
130 // This function is to be used to increment a
133 // It's strongly encouraged to use this
134 // function instead of open coding a simple
138 will be displayed like this:
140 .. c:function:: int inc(int val)
143 :param val: the value to increment
144 :return: the incremented value
146 This function is to be used to increment a
149 It's strongly encouraged to use this
150 function instead of open coding a simple
153 Intermediate Representation
154 ---------------------------
155 .. c:autodoc:: Documentation/sphinx/ir.py