1========================== 2Sphinx Quickstart Template 3========================== 4 5This article is intended to take someone in the state of “I want to write documentation and get it added to LLVM’s docs” and help them start writing documentation as fast as possible and with as little nonsense as possible. 6 7.. contents:: 8 :local: 9 10Overview 11======== 12 13LLVM documentation is written in `reStructuredText`_, a markup syntax similar to markdown (but much more powerful). The LLVM documentation site itself uses `Sphinx`_, a documentation generator originally written for Python documentation. 14 15.. _`reStructuredText`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html 16.. _`Sphinx`: http://www.sphinx-doc.org 17 18How to use this template 19======================== 20 21This article is located in ``docs/SphinxQuickstartTemplate.rst``. To use it as a template, make a copy and open it in a text editor. You can then write your docs, and then send the new article to llvm-commits for review. 22 23To view the restructuredText source file for this article, click **Show Source** on the right sidebar. 24 25Authoring Guidelines 26==================== 27 28Focus on *content*. It is easy to fix the Sphinx (reStructuredText) syntax 29later if necessary, although reStructuredText tries to imitate common 30plain-text conventions so it should be quite natural. A basic knowledge of 31reStructuredText syntax is useful when writing the document, so the last 32~half of this document (starting with `Example Section`_) gives examples 33which should cover 99% of use cases. 34 35Let me say that again: focus on *content*. But if you really need to verify 36Sphinx's output, see ``docs/README.txt`` for information. Once you have finished with the content, please send the ``.rst`` file to 37llvm-commits for review. 38 39Creating New Articles 40--------------------- 41 42Before creating a new article, consider the following questions: 43 44#. Why would I want to read this document? 45 46#. What should I know to be able to follow along with this document? 47 48#. What will I have learned by the end of this document? 49 50A standard best practice is to make your articles task-oriented. You generally should not be writing documentation that isn't based around "how to" do something 51unless there's already an existing "how to" article for the topic you're documenting. The reason for this is that without a "how to" article to read first, it might be difficult for 52someone unfamiliar with the topic to understand a more advanced, conceptual article. 53 54When creating a task-oriented article, follow existing LLVM articles by giving it a filename that starts with ``HowTo*.rst``. This format is usually the easiest for another person to understand and also the most useful. 55 56Focus on content (yes, I had to say it again). 57 58The rest of this document shows example reStructuredText markup constructs 59that are meant to be read by you in your text editor after you have copied 60this file into a new file for the documentation you are about to write. 61 62Example Section 63=============== 64 65An article can contain one or more sections (i.e., headings). Sections (like ``Example Section`` above) help give your document its 66structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``) 67as are used in this document. The adornment must be the same length as the 68text above it. For Vim users, variations of ``yypVr=`` might be handy. 69 70Example Nested Subsection 71------------------------- 72 73Subsections can also be nested beneath other subsections. For more information on sections, see Sphinx's `reStructuredText Primer`_. 74 75.. _`reStructuredText Primer`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections 76 77Text Formatting 78=============== 79 80Text can be *emphasized*, **bold**, or ``monospace``. 81 82To create a new paragraph, simply insert a blank line. 83 84Links 85===== 86 87You can format a link `like this <https://llvm.org/>`_. A more `sophisticated syntax`_ allows you to place the ``.. _`link text`: <URL>`` block 88pretty much anywhere else in the document. This is useful when linking to especially long URLs. 89 90.. _`sophisticated syntax`: http://en.wikipedia.org/wiki/LLVM 91 92Lists 93===== 94 95restructuredText allows you to create ordered lists... 96 97#. A list starting with ``#.`` will be automatically numbered. 98 99#. This is a second list element. 100 101 #. Use indentation to create nested lists. 102 103...as well as unordered lists: 104 105* Stuff. 106 107 + Deeper stuff. 108 109* More stuff. 110 111Code Blocks 112=========== 113 114You can make blocks of code like this: 115 116.. code-block:: c++ 117 118 int main() { 119 return 0; 120 } 121 122For a shell session, use a ``console`` code block (some existing docs use 123``bash``): 124 125.. code-block:: console 126 127 $ echo "Goodbye cruel world!" 128 $ rm -rf / 129 130If you need to show LLVM IR use the ``llvm`` code block. 131 132.. code-block:: llvm 133 134 define i32 @test1() { 135 entry: 136 ret i32 0 137 } 138 139Some other common code blocks you might need are ``c``, ``objc``, ``make``, 140and ``cmake``. If you need something beyond that, you can look at the `full 141list`_ of supported code blocks. 142 143.. _`full list`: http://pygments.org/docs/lexers/ 144 145However, don't waste time fiddling with syntax highlighting when you could 146be adding meaningful content. When in doubt, show preformatted text 147without any syntax highlighting like this: 148 149:: 150 151 . 152 +:. 153 ..:: :: 154 .++:+:: ::+:.:. 155 .:+ : 156 ::.::..:: .+. 157 ..:+ :: : 158 ......+:. .. 159 :++. .. : 160 .+:::+:: : 161 .. . .+ :: 162 +.: .::+. 163 ...+. .: . 164 .++:.. 165 ... 166 167 168