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