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
168Generating the documentation
169============================
170
171You can generate the HTML documentation from the sources locally if you want to
172see what they would look like. In addition to the normal
173`build tools <docs/GettingStarted.html>`_
174you need to install `Sphinx`_ and the
175`recommonmark <https://recommonmark.readthedocs.io/en/latest/>`_ extension.
176
177On Debian you can install these with:
178
179.. code-block:: console
180
181   sudo apt install -y sphinx-doc python-recommonmark-doc
182
183On Ubuntu use pip to get an up-to-date version of recommonmark:
184
185.. code-block:: console
186
187   sudo pip install sphinx recommonmark
188
189Then run cmake to build the documentation inside the ``llvm-project`` checkout:
190
191.. code-block:: console
192
193   mkdir build
194   cd build
195   cmake -DLLVM_ENABLE_SPHINX=On ../llvm
196   cmake --build . --target docs-llvm-html
197
198In case you already have the Cmake build set up and want to reuse that,
199just set the CMake variable ``LLVM_ENABLE_SPHINX=On``.
200
201After that you find the generated documentation in ``build/docs/html``
202folder.
203