doc-guide.rst 3.3 KB

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