Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> --- Documentation/doc-guide.rst | 119 ++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/Documentation/doc-guide.rst b/Documentation/doc-guide.rst index cbc3f842f..334502c0f 100644 --- a/Documentation/doc-guide.rst +++ b/Documentation/doc-guide.rst @@ -24,9 +24,128 @@ list the name of the files with real documentation. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _MarkDown: https://en.wikipedia.org/wiki/Markdown + +.. _rest-markup: + +Mnimal reST cheatsheet +---------------------- + +Basic inline markup is: + +* italic: ``*italic*`` gives *italic* +* bold: ``**bold**`` gives **bold** +* monospace: ````monospace```` gives ``monospace`` + +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 + #. with two items + + 1. this is an explicitely 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 hightlighting 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 + ``++``. -- 2.17.0 -- To unsubscribe from this list: send the line "unsubscribe linux-sparse" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
