docs/SphinxQuickstartTemplate.rst

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