Sphinx Quickstart Template
==========================
-.. sectionauthor:: Sean Silva <silvas@purdue.edu>
-
Introduction and Quickstart
===========================
~half of this document (starting with `Example Section`_) gives examples
which should cover 99% of use cases.
-Let me say that again: focus on *content*.
+Let me say that again: focus on *content*. But if you really need to verify
+Sphinx's output, see ``docs/README.txt`` for information.
Once you have finished with the content, please send the ``.rst`` file to
llvm-commits for review.
Use blank lines to separate paragraphs.
-Headings (like ``Example Section`` just above) give your document
+Headings (like ``Example Section`` just above) give your document its
structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``)
as are used in this document. The adornment must be the same length as the
text above it. For Vim users, variations of ``yypVr=`` might be handy.
#. This is a second list element.
- #. They nest too.
+ #. Use indentation to create nested lists.
You can also use unordered lists.
.. code-block:: c++
int main() {
- return 0
+ return 0;
}
-For a shell session, use a ``bash`` code block:
+For a shell session, use a ``console`` code block (some existing docs use
+``bash``):
-.. code-block:: bash
+.. code-block:: console
$ echo "Goodbye cruel world!"
$ rm -rf /
If you need to show LLVM IR use the ``llvm`` code block.
-You can show preformatted text without any syntax highlighting like this:
+.. code-block:: llvm
+
+ define i32 @test1() {
+ entry:
+ ret i32 0
+ }
+
+Some other common code blocks you might need are ``c``, ``objc``, ``make``,
+and ``cmake``. If you need something beyond that, you can look at the `full
+list`_ of supported code blocks.
+
+.. _`full list`: http://pygments.org/docs/lexers/
+
+However, don't waste time fiddling with syntax highlighting when you could
+be adding meaningful content. When in doubt, show preformatted text
+without any syntax highlighting like this:
::