How to write sparse documentation

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.

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:

int foo(int a)
{
        return a + 1;
}

Autodoc

Sparse source files may contain documentation inside block-comments specifically formatted:

///
// Here is some doc
// and here is some more.

More precisely, a doc-block begins with a line containing only /// and continues with lines beginning by // followed by either a space, a tab or nothing, the first space after // is ignored.

For functions, some additional syntax must be respected inside the block-comment:

///
// <mandatory short one-line description>
// <optional blank line>
// @<1st parameter's name>: <description>
// @<2nd parameter's name>: <long description
// <tab>which needs multiple lines>
// @return: <description> (absent for void functions)
// <optional blank line>
// <optional long multi-line description>
int somefunction(void *ptr, int count);

Inside the description fields, parameter’s names can be referenced by using @<parameter name>. A function doc-block must directly precede the function it documents. This function can span multiple lines and can either be a function prototype (ending with ;) or a function definition.

Some future versions will also allow to document structures, unions, enums, typedefs and variables.

This documentation can be extracted into a .rst document by using the autodoc directive:

.. c:autodoc:: file.c

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:

int inc(int val)

Parameters:

• val – the value to increment

Returns:

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

To document the instructions used in the intermediate representation a new domain is defined: ‘ir’ with a directive:

.. op: <OP_NAME>
        <description of OP_NAME>
        ...

This is equivalent to using a definition list but with the name also placed in the index (with ‘IR instruction’ as descriptions).