docs/SphinxQuickstartTemplate.rst

   1 ==========================
   2 Sphinx Quickstart Template
   3 ==========================
   4
   5 Introduction and Quickstart
   6 ===========================
   7
   8 This document is meant to get you writing documentation as fast as possible
   9 even if you have no previous experience with Sphinx. The goal is to take
  10 someone in the state of "I want to write documentation and get it added to
  11 LLVM's docs" and turn that into useful documentation mailed to llvm-commits
  12 with as little nonsense as possible.
  13
  14 You can find this document in ``docs/SphinxQuickstartTemplate.rst``. You
  15 should copy it, open the new file in your text editor, write your docs, and
  16 then send the new document to llvm-commits for review.
  17
  18 Focus on *content*. It is easy to fix the Sphinx (reStructuredText) syntax
  19 later if necessary, although reStructuredText tries to imitate common
  20 plain-text conventions so it should be quite natural. A basic knowledge of
  21 reStructuredText syntax is useful when writing the document, so the last
  22 ~half of this document (starting with `Example Section`_) gives examples
  23 which should cover 99% of use cases.
  24
  25 Let me say that again: focus on *content*. But if you really need to verify
  26 Sphinx's output, see ``docs/README.txt`` for information.
  27
  28 Once you have finished with the content, please send the ``.rst`` file to
  29 llvm-commits for review.
  30
  31 Guidelines
  32 ==========
  33
  34 Try to answer the following questions in your first section:
  35
  36 #. Why would I want to read this document?
  37
  38 #. What should I know to be able to follow along with this document?
  39
  40 #. What will I have learned by the end of this document?
  41
  42 Common names for the first section are ``Introduction``, ``Overview``, or
  43 ``Background``.
  44
  45 If possible, make your document a "how to". Give it a name ``HowTo*.rst``
  46 like the other "how to" documents. This format is usually the easiest
  47 for another person to understand and also the most useful.
  48
  49 You generally should not be writing documentation other than a "how to"
  50 unless there is already a "how to" about your topic. The reason for this
  51 is that without a "how to" document to read first, it is difficult for a
  52 person to understand a more advanced document.
  53
  54 Focus on content (yes, I had to say it again).
  55
  56 The rest of this document shows example reStructuredText markup constructs
  57 that are meant to be read by you in your text editor after you have copied
  58 this file into a new file for the documentation you are about to write.
  59
  60 Example Section
  61 ===============
  62
  63 Your text can be *emphasized*, **bold**, or ``monospace``.
  64
  65 Use blank lines to separate paragraphs.
  66
  67 Headings (like ``Example Section`` just above) give your document its
  68 structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``)
  69 as are used in this document. The adornment must be the same length as the
  70 text above it. For Vim users, variations of ``yypVr=`` might be handy.
  71
  72 Example Subsection
  73 ------------------
  74
  75 Make a link `like this <http://llvm.org/>`_. There is also a more
  76 sophisticated syntax which `can be more readable`_ for longer links since
  77 it disrupts the flow less. You can put the ``.. _`link text`: <URL>`` block
  78 pretty much anywhere later in the document.
  79
  80 .. _`can be more readable`: http://en.wikipedia.org/wiki/LLVM
  81
  82 Lists can be made like this:
  83
  84 #. A list starting with ``#.`` will be automatically numbered.
  85
  86 #. This is a second list element.
  87
  88    #. Use indentation to create nested lists.
  89
  90 You can also use unordered lists.
  91
  92 * Stuff.
  93
  94   + Deeper stuff.
  95
  96 * More stuff.
  97
  98 Example Subsubsection
  99 ^^^^^^^^^^^^^^^^^^^^^
 100
 101 You can make blocks of code like this:
 102
 103 .. code-block:: c++
 104
 105    int main() {
 106      return 0;
 107    }
 108
 109 For a shell session, use a ``console`` code block (some existing docs use
 110 ``bash``):
 111
 112 .. code-block:: console
 113
 114    $ echo "Goodbye cruel world!"
 115    $ rm -rf /
 116
 117 If you need to show LLVM IR use the ``llvm`` code block.
 118
 119 .. code-block:: llvm
 120
 121    define i32 @test1() {
 122    entry:
 123      ret i32 0
 124    }
 125
 126 Some other common code blocks you might need are ``c``, ``objc``, ``make``,
 127 and ``cmake``. If you need something beyond that, you can look at the `full
 128 list`_ of supported code blocks.
 129
 130 .. _`full list`: http://pygments.org/docs/lexers/
 131
 132 However, don't waste time fiddling with syntax highlighting when you could
 133 be adding meaningful content. When in doubt, show preformatted text
 134 without any syntax highlighting like this:
 135
 136 ::
 137
 138                           .
 139                            +:.
 140                        ..:: ::
 141                     .++:+:: ::+:.:.
 142                    .:+           :
 143             ::.::..::            .+.
 144           ..:+    ::              :
 145     ......+:.                    ..
 146           :++.    ..              :
 147             .+:::+::              :
 148             ..   . .+            ::
 149                      +.:      .::+.
 150                       ...+. .: .
 151                          .++:..
 152                           ...
 153
 154 Hopefully you won't need to be this deep
 155 """"""""""""""""""""""""""""""""""""""""
 156
 157 If you need to do fancier things than what has been shown in this document,
 158 you can mail the list or check Sphinx's `reStructuredText Primer`_.
 159
 160 .. _`reStructuredText Primer`: http://sphinx.pocoo.org/rest.html