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