1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Sphinx Quickstart Template — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="How to submit an LLVM bug report" href="HowToSubmitABug.html" />
<link rel="prev" title="LLVM Community Support Policy" href="SupportPolicy.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="SupportPolicy.html" title="LLVM Community Support Policy"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" accesskey="U">Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">Sphinx Quickstart Template</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/SphinxQuickstartTemplate.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="sphinx-quickstart-template">
<h1>Sphinx Quickstart Template<a class="headerlink" href="#sphinx-quickstart-template" title="Permalink to this headline">¶</a></h1>
<p>This 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.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#overview" id="id1">Overview</a></p></li>
<li><p><a class="reference internal" href="#how-to-use-this-template" id="id2">How to use this template</a></p></li>
<li><p><a class="reference internal" href="#authoring-guidelines" id="id3">Authoring Guidelines</a></p>
<ul>
<li><p><a class="reference internal" href="#creating-new-articles" id="id4">Creating New Articles</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#example-section" id="id5">Example Section</a></p>
<ul>
<li><p><a class="reference internal" href="#example-nested-subsection" id="id6">Example Nested Subsection</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#text-formatting" id="id7">Text Formatting</a></p></li>
<li><p><a class="reference internal" href="#links" id="id8">Links</a></p></li>
<li><p><a class="reference internal" href="#lists" id="id9">Lists</a></p></li>
<li><p><a class="reference internal" href="#code-blocks" id="id10">Code Blocks</a></p></li>
<li><p><a class="reference internal" href="#generating-the-documentation" id="id11">Generating the documentation</a></p></li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>LLVM documentation is written in <a class="reference external" href="http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">reStructuredText</a>, a markup syntax similar to markdown (but much more powerful). The LLVM documentation site itself uses <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a>, a documentation generator originally written for Python documentation.</p>
</div>
<div class="section" id="how-to-use-this-template">
<h2><a class="toc-backref" href="#id2">How to use this template</a><a class="headerlink" href="#how-to-use-this-template" title="Permalink to this headline">¶</a></h2>
<p>This article is located in <code class="docutils literal notranslate"><span class="pre">docs/SphinxQuickstartTemplate.rst</span></code>. 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.</p>
<p>To view the restructuredText source file for this article, click <strong>Show Source</strong> on the right sidebar.</p>
</div>
<div class="section" id="authoring-guidelines">
<h2><a class="toc-backref" href="#id3">Authoring Guidelines</a><a class="headerlink" href="#authoring-guidelines" title="Permalink to this headline">¶</a></h2>
<p>Focus on <em>content</em>. It is easy to fix the Sphinx (reStructuredText) syntax
later if necessary, although reStructuredText tries to imitate common
plain-text conventions so it should be quite natural. A basic knowledge of
reStructuredText syntax is useful when writing the document, so the last
~half of this document (starting with <a class="reference internal" href="#example-section">Example Section</a>) gives examples
which should cover 99% of use cases.</p>
<p>Let me say that again: focus on <em>content</em>. But if you really need to verify
Sphinx’s output, see <code class="docutils literal notranslate"><span class="pre">docs/README.txt</span></code> for information. Once you have finished with the content, please send the <code class="docutils literal notranslate"><span class="pre">.rst</span></code> file to
llvm-commits for review.</p>
<div class="section" id="creating-new-articles">
<h3><a class="toc-backref" href="#id4">Creating New Articles</a><a class="headerlink" href="#creating-new-articles" title="Permalink to this headline">¶</a></h3>
<p>Before creating a new article, consider the following questions:</p>
<ol class="arabic simple">
<li><p>Why would I want to read this document?</p></li>
<li><p>What should I know to be able to follow along with this document?</p></li>
<li><p>What will I have learned by the end of this document?</p></li>
</ol>
<p>A 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
unless 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
someone unfamiliar with the topic to understand a more advanced, conceptual article.</p>
<p>When creating a task-oriented article, follow existing LLVM articles by giving it a filename that starts with <code class="docutils literal notranslate"><span class="pre">HowTo*.rst</span></code>. This format is usually the easiest for another person to understand and also the most useful.</p>
<p>Focus on content (yes, I had to say it again).</p>
<p>The rest of this document shows example reStructuredText markup constructs
that are meant to be read by you in your text editor after you have copied
this file into a new file for the documentation you are about to write.</p>
</div>
</div>
<div class="section" id="example-section">
<h2><a class="toc-backref" href="#id5">Example Section</a><a class="headerlink" href="#example-section" title="Permalink to this headline">¶</a></h2>
<p>An article can contain one or more sections (i.e., headings). Sections (like <code class="docutils literal notranslate"><span class="pre">Example</span> <span class="pre">Section</span></code> above) help give your document its
structure. Use the same kind of adornments (e.g. <code class="docutils literal notranslate"><span class="pre">======</span></code> vs. <code class="docutils literal notranslate"><span class="pre">------</span></code>)
as are used in this document. The adornment must be the same length as the
text above it. For Vim users, variations of <code class="docutils literal notranslate"><span class="pre">yypVr=</span></code> might be handy.</p>
<div class="section" id="example-nested-subsection">
<h3><a class="toc-backref" href="#id6">Example Nested Subsection</a><a class="headerlink" href="#example-nested-subsection" title="Permalink to this headline">¶</a></h3>
<p>Subsections can also be nested beneath other subsections. For more information on sections, see Sphinx’s <a class="reference external" href="http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections">reStructuredText Primer</a>.</p>
</div>
</div>
<div class="section" id="text-formatting">
<h2><a class="toc-backref" href="#id7">Text Formatting</a><a class="headerlink" href="#text-formatting" title="Permalink to this headline">¶</a></h2>
<p>Text can be <em>emphasized</em>, <strong>bold</strong>, or <code class="docutils literal notranslate"><span class="pre">monospace</span></code>.</p>
<p>To create a new paragraph, simply insert a blank line.</p>
</div>
<div class="section" id="links">
<h2><a class="toc-backref" href="#id8">Links</a><a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
<p>You can format a link <a class="reference external" href="https://llvm.org/">like this</a>. A more <a class="reference external" href="http://en.wikipedia.org/wiki/LLVM">sophisticated syntax</a> allows you to place the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">_`link</span> <span class="pre">text`:</span> <span class="pre"><URL></span></code> block
pretty much anywhere else in the document. This is useful when linking to especially long URLs.</p>
</div>
<div class="section" id="lists">
<h2><a class="toc-backref" href="#id9">Lists</a><a class="headerlink" href="#lists" title="Permalink to this headline">¶</a></h2>
<p>restructuredText allows you to create ordered lists…</p>
<ol class="arabic simple">
<li><p>A list starting with <code class="docutils literal notranslate"><span class="pre">#.</span></code> will be automatically numbered.</p></li>
<li><p>This is a second list element.</p>
<ol class="arabic simple">
<li><p>Use indentation to create nested lists.</p></li>
</ol>
</li>
</ol>
<p>…as well as unordered lists:</p>
<ul class="simple">
<li><p>Stuff.</p>
<ul>
<li><p>Deeper stuff.</p></li>
</ul>
</li>
<li><p>More stuff.</p></li>
</ul>
</div>
<div class="section" id="code-blocks">
<h2><a class="toc-backref" href="#id10">Code Blocks</a><a class="headerlink" href="#code-blocks" title="Permalink to this headline">¶</a></h2>
<p>You can make blocks of code like this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>For a shell session, use a <code class="docutils literal notranslate"><span class="pre">console</span></code> code block (some existing docs use
<code class="docutils literal notranslate"><span class="pre">bash</span></code>):</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"Goodbye cruel world!"</span>
<span class="gp">$</span> rm -rf /
</pre></div>
</div>
<p>If you need to show LLVM IR use the <code class="docutils literal notranslate"><span class="pre">llvm</span></code> code block.</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i32</span> <span class="vg">@test1</span><span class="p">()</span> <span class="p">{</span>
<span class="nl">entry:</span>
<span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Some other common code blocks you might need are <code class="docutils literal notranslate"><span class="pre">c</span></code>, <code class="docutils literal notranslate"><span class="pre">objc</span></code>, <code class="docutils literal notranslate"><span class="pre">make</span></code>,
and <code class="docutils literal notranslate"><span class="pre">cmake</span></code>. If you need something beyond that, you can look at the <a class="reference external" href="http://pygments.org/docs/lexers/">full
list</a> of supported code blocks.</p>
<p>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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">.</span>
<span class="o">+</span><span class="p">:</span><span class="o">.</span>
<span class="o">..</span><span class="p">::</span> <span class="p">::</span>
<span class="o">.++</span><span class="p">:</span><span class="o">+</span><span class="p">::</span> <span class="p">::</span><span class="o">+</span><span class="p">:</span><span class="o">.</span><span class="p">:</span><span class="o">.</span>
<span class="o">.</span><span class="p">:</span><span class="o">+</span> <span class="p">:</span>
<span class="p">::</span><span class="o">.</span><span class="p">::</span><span class="o">..</span><span class="p">::</span> <span class="o">.+.</span>
<span class="o">..</span><span class="p">:</span><span class="o">+</span> <span class="p">::</span> <span class="p">:</span>
<span class="o">......+</span><span class="p">:</span><span class="o">.</span> <span class="o">..</span>
<span class="p">:</span><span class="o">++.</span> <span class="o">..</span> <span class="p">:</span>
<span class="o">.+</span><span class="p">:::</span><span class="o">+</span><span class="p">::</span> <span class="p">:</span>
<span class="o">..</span> <span class="o">.</span> <span class="o">.+</span> <span class="p">::</span>
<span class="o">+.</span><span class="p">:</span> <span class="o">.</span><span class="p">::</span><span class="o">+.</span>
<span class="o">...+.</span> <span class="o">.</span><span class="p">:</span> <span class="o">.</span>
<span class="o">.++</span><span class="p">:</span><span class="o">..</span>
<span class="o">...</span>
</pre></div>
</div>
</div>
<div class="section" id="generating-the-documentation">
<h2><a class="toc-backref" href="#id11">Generating the documentation</a><a class="headerlink" href="#generating-the-documentation" title="Permalink to this headline">¶</a></h2>
<p>You can generate the HTML documentation from the sources locally if you want to
see what they would look like. In addition to the normal
<a class="reference external" href="docs/GettingStarted.html">build tools</a>
you need to install <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> and the
<a class="reference external" href="https://recommonmark.readthedocs.io/en/latest/">recommonmark</a> extension.</p>
<p>On Debian you can install these with:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">sudo apt install -y sphinx-doc python-recommonmark-doc</span>
</pre></div>
</div>
<p>On Ubuntu use pip to get an up-to-date version of recommonmark:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">sudo pip install sphinx recommonmark</span>
</pre></div>
</div>
<p>Then run cmake to build the documentation inside the <code class="docutils literal notranslate"><span class="pre">llvm-project</span></code> checkout:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">mkdir build</span>
<span class="go">cd build</span>
<span class="go">cmake -DLLVM_ENABLE_SPHINX=On ../llvm</span>
<span class="go">cmake --build . --target docs-llvm-html</span>
</pre></div>
</div>
<p>In case you already have the Cmake build set up and want to reuse that,
just set the CMake variable <code class="docutils literal notranslate"><span class="pre">LLVM_ENABLE_SPHINX=On</span></code>.</p>
<p>After that you find the generated documentation in <code class="docutils literal notranslate"><span class="pre">build/docs/html</span></code>
folder.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
>next</a> |</li>
<li class="right" >
<a href="SupportPolicy.html" title="LLVM Community Support Policy"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" >Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">Sphinx Quickstart Template</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
