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