diff options
Diffstat (limited to 'docs/SphinxQuickstartTemplate.rst')
| -rw-r--r-- | docs/SphinxQuickstartTemplate.rst | 51 |
1 files changed, 43 insertions, 8 deletions
diff --git a/docs/SphinxQuickstartTemplate.rst b/docs/SphinxQuickstartTemplate.rst index 75d916368e33..fe6e44a27cea 100644 --- a/docs/SphinxQuickstartTemplate.rst +++ b/docs/SphinxQuickstartTemplate.rst @@ -2,8 +2,6 @@ Sphinx Quickstart Template ========================== -.. sectionauthor:: Sean Silva <silvas@purdue.edu> - Introduction and Quickstart =========================== @@ -24,7 +22,8 @@ reStructuredText syntax is useful when writing the document, so the last ~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. @@ -65,7 +64,7 @@ Your text can be *emphasized*, **bold**, or ``monospace``. 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. @@ -86,7 +85,7 @@ Lists can be made like this: #. This is a second list element. - #. They nest too. + #. Use indentation to create nested lists. You can also use unordered lists. @@ -104,18 +103,54 @@ You can make blocks of code like this: .. 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. +.. 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: + +:: + + . + +:. + ..:: :: + .++:+:: ::+:.:. + .:+ : + ::.::..:: .+. + ..:+ :: : + ......+:. .. + :++. .. : + .+:::+:: : + .. . .+ :: + +.: .::+. + ...+. .: . + .++:.. + ... + Hopefully you won't need to be this deep """""""""""""""""""""""""""""""""""""""" |