diff options
| author | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-16 14:03:18 +0200 |
|---|---|---|
| committer | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-21 03:06:27 +0200 |
| commit | 1e76c0fb84430760d8a63f67b8cfe8f8bab4efbf (patch) | |
| tree | 6816f92f4ed6380d4cb14410eb175726020b38d4 /Documentation | |
| parent | 62973b78d4c7c7b7835b682383a9b38287cdf459 (diff) | |
| download | sparse-dev-1e76c0fb84430760d8a63f67b8cfe8f8bab4efbf.tar.gz | |
autodoc: add a small cheatsheet for reST markup
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/doc-guide.rst | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/Documentation/doc-guide.rst b/Documentation/doc-guide.rst index fb8f5440..80ec82c2 100644 --- a/Documentation/doc-guide.rst +++ b/Documentation/doc-guide.rst @@ -24,9 +24,128 @@ lists the names of the files with real documentation. .. _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 + ``++``. |