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
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Markdown 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="MemorySSA" href="MemorySSA.html" />
<link rel="prev" title="LLVM Loop Terminology (and Canonical Forms)" href="LoopTerminology.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="MemorySSA.html" title="MemorySSA"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="LoopTerminology.html" title="LLVM Loop Terminology (and Canonical Forms)"
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="UserGuides.html" accesskey="U">User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">Markdown 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/MarkdownQuickstartTemplate.md.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="markdown-quickstart-template">
<h1>Markdown Quickstart Template<a class="headerlink" href="#markdown-quickstart-template" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction-and-quickstart">
<h2>Introduction and Quickstart<a class="headerlink" href="#introduction-and-quickstart" title="Permalink to this headline">¶</a></h2>
<p>This document is meant to get you writing documentation as fast as possible
even if you have no previous experience with Markdown. The goal is to take
someone in the state of “I want to write documentation and get it added to
LLVM’s docs” and turn that into useful documentation mailed to llvm-commits
with as little nonsense as possible.</p>
<p>You can find this document in <code class="docutils literal notranslate"><span class="pre">docs/MarkdownQuickstartTemplate.md</span></code>. You
should copy it, open the new file in your text editor, write your docs, and
then send the new document to llvm-commits for review.</p>
<p>Focus on <em>content</em>. It is easy to fix the Markdown syntax
later if necessary, although Markdown tries to imitate common
plain-text conventions so it should be quite natural. A basic knowledge of
Markdown syntax is useful when writing the document, so the last
~half of this document (starting with <a class="reference external" 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.</p>
<p>Once you have finished with the content, please send the <code class="docutils literal notranslate"><span class="pre">.md</span></code> file to
llvm-commits for review.</p>
</div>
<div class="section" id="guidelines">
<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this headline">¶</a></h2>
<p>Try to answer the following questions in your first section:</p>
<ol class="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>Common names for the first section are <code class="docutils literal notranslate"><span class="pre">Introduction</span></code>, <code class="docutils literal notranslate"><span class="pre">Overview</span></code>, or
<code class="docutils literal notranslate"><span class="pre">Background</span></code>.</p>
<p>If possible, make your document a “how to”. Give it a name <code class="docutils literal notranslate"><span class="pre">HowTo*.md</span></code>
like the other “how to” documents. This format is usually the easiest
for another person to understand and also the most useful.</p>
<p>You generally should not be writing documentation other than a “how to”
unless there is already a “how to” about your topic. The reason for this
is that without a “how to” document to read first, it is difficult for a
person to understand a more advanced document.</p>
<p>Focus on content (yes, I had to say it again).</p>
<p>The rest of this document shows example Markdown 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 class="section" id="example-section">
<h2>Example Section<a class="headerlink" href="#example-section" title="Permalink to this headline">¶</a></h2>
<p>Your text can be <em>emphasized</em>, <strong>bold</strong>, or <code class="docutils literal notranslate"><span class="pre">monospace</span></code>.</p>
<p>Use blank lines to separate paragraphs.</p>
<p>Headings (like <code class="docutils literal notranslate"><span class="pre">Example</span> <span class="pre">Section</span></code> just above) give your document its
structure.</p>
<div class="section" id="example-subsection">
<h3>Example Subsection<a class="headerlink" href="#example-subsection" title="Permalink to this headline">¶</a></h3>
<p>Make a link <a class="reference external" href="https://llvm.org/">like this</a>. There is also a more
sophisticated syntax which <a class="reference external" href="http://en.wikipedia.org/wiki/LLVM">can be more readable</a> for longer links since
it disrupts the flow less. You can put the <code class="docutils literal notranslate"><span class="pre">[link</span> <span class="pre">name]:</span> <span class="pre"><URL></span></code> block
pretty much anywhere later in the document.</p>
<p>Lists can be made like this:</p>
<ol class="simple">
<li><p>A list starting with <code class="docutils literal notranslate"><span class="pre">[0-9].</span></code> will be automatically numbered.</p></li>
<li><p>This is a second list element.</p>
<ol class="simple">
<li><p>Use indentation to create nested lists.</p></li>
</ol>
</li>
</ol>
<p>You can also use 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 class="section" id="example-subsubsection">
<h4>Example Subsubsection<a class="headerlink" href="#example-subsubsection" title="Permalink to this headline">¶</a></h4>
<p>You can make blocks of code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">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>As an extension to markdown, you can also specify a highlighter to use.</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.</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 class="section" id="hopefully-you-won-t-need-to-be-this-deep">
<h5>Hopefully you won’t need to be this deep<a class="headerlink" href="#hopefully-you-won-t-need-to-be-this-deep" title="Permalink to this headline">¶</a></h5>
<p>If you need to do fancier things than what has been shown in this document,
you can mail the list or check the <a class="reference external" href="http://spec.commonmark.org/0.28/">Common Mark spec</a>. Sphinx specific
integration documentation can be found in the <a class="reference external" href="http://recommonmark.readthedocs.io/en/latest/index.html">recommonmark docs</a>.</p>
</div>
</div>
</div>
</div>
<div class="section" id="generating-the-documentation">
<h2>Generating the documentation<a class="headerlink" href="#generating-the-documentation" title="Permalink to this headline">¶</a></h2>
<p>see <a class="reference external" href="SphinxQuickstartTemplate.html#generating-the-documentation">Sphinx Quickstart Template</a></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="MemorySSA.html" title="MemorySSA"
>next</a> |</li>
<li class="right" >
<a href="LoopTerminology.html" title="LLVM Loop Terminology (and Canonical Forms)"
>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="UserGuides.html" >User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">Markdown 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>
|
