123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156 |
- 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
|