-
Notifications
You must be signed in to change notification settings - Fork 0
/
sphinx_intro.html
233 lines (219 loc) · 12.3 KB
/
sphinx_intro.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sphinx Introduction for LLVM Developers — lld 11 documentation</title>
<link rel="stylesheet" href="_static/llvm.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="WebAssembly lld port" href="WebAssembly.html" />
<link rel="prev" title="Open Projects" href="open_projects.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 Documentation"/></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="WebAssembly.html" title="WebAssembly lld port"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="open_projects.html" title="Open Projects"
accesskey="P">previous</a> |</li>
<li><a href="index.html">lld Home</a> | </li>
<li class="nav-item nav-item-1"><a href="AtomLLD.html" accesskey="U">ATOM-based lld</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Sphinx Introduction for LLVM Developers</a><ul>
<li><a class="reference internal" href="#quickstart">Quickstart</a><ul>
<li><a class="reference internal" href="#installing-sphinx">Installing Sphinx</a></li>
<li><a class="reference internal" href="#building-the-documentation">Building the documentation</a></li>
<li><a class="reference internal" href="#writing-documentation">Writing documentation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#learning-more">Learning More</a></li>
<li><a class="reference internal" href="#installing-sphinx-in-a-virtual-environment">Installing Sphinx in a Virtual Environment</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="open_projects.html"
title="previous chapter">Open Projects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="WebAssembly.html"
title="next chapter">WebAssembly lld port</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/sphinx_intro.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#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-introduction-for-llvm-developers">
<span id="sphinx-intro"></span><h1>Sphinx Introduction for LLVM Developers<a class="headerlink" href="#sphinx-introduction-for-llvm-developers" title="Permalink to this headline">¶</a></h1>
<p>This document is intended as a short and simple introduction to the Sphinx
documentation generation system for LLVM developers.</p>
<div class="section" id="quickstart">
<h2>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h2>
<p>To get started writing documentation, you will need to:</p>
<blockquote>
<div><ol class="arabic simple">
<li>Have the Sphinx tools <a class="reference internal" href="#installing-sphinx"><span class="std std-ref">installed</span></a>.</li>
<li>Understand how to <a class="reference internal" href="#building-the-documentation"><span class="std std-ref">build the documentation</span></a>.</li>
<li>Start <a class="reference internal" href="#writing-documentation"><span class="std std-ref">writing documentation</span></a>!</li>
</ol>
</div></blockquote>
<div class="section" id="installing-sphinx">
<span id="id1"></span><h3>Installing Sphinx<a class="headerlink" href="#installing-sphinx" title="Permalink to this headline">¶</a></h3>
<p>You should be able to install Sphinx using the standard Python package
installation tool <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>, as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.1.3
... more lines here ..
</pre></div>
</div>
<p>If you do not have root access (or otherwise want to avoid installing Sphinx in
system directories) see the section on <a class="reference internal" href="#installing-sphinx-in-a-venv"><span class="std std-ref">Installing Sphinx in a Virtual Environment</span></a> .</p>
<p>If you do not have the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> tool on your system, you should be able
to install it using:</p>
<blockquote>
<div><dl class="docutils">
<dt>Linux</dt>
<dd>Use your distribution’s standard package management tool to install it,
i.e., <code class="docutils literal notranslate"><span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">easy_install</span></code> or <code class="docutils literal notranslate"><span class="pre">yum</span> <span class="pre">install</span> <span class="pre">easy_install</span></code>.</dd>
<dt>macOS</dt>
<dd>All modern macOS systems come with <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> as part of the base
system.</dd>
<dt>Windows</dt>
<dd>See the <a class="reference external" href="http://pypi.python.org/pypi/setuptools">setuptools</a> package web
page for instructions.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="building-the-documentation">
<span id="id2"></span><h3>Building the documentation<a class="headerlink" href="#building-the-documentation" title="Permalink to this headline">¶</a></h3>
<p>In order to build the documentation need to add <code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_SPHINX=ON</span></code> to
your <code class="docutils literal notranslate"><span class="pre">cmake</span></code> command. Once you do this you can build the docs using
<code class="docutils literal notranslate"><span class="pre">docs-lld-html</span></code> build (<code class="docutils literal notranslate"><span class="pre">ninja</span></code> or <code class="docutils literal notranslate"><span class="pre">make</span></code>) target.</p>
<p>That build target will invoke <code class="docutils literal notranslate"><span class="pre">sphinx-build</span></code> with the appropriate options for
the project, and generate the HTML documentation in a <code class="docutils literal notranslate"><span class="pre">tools/lld/docs/html</span></code>
subdirectory.</p>
</div>
<div class="section" id="writing-documentation">
<span id="id3"></span><h3>Writing documentation<a class="headerlink" href="#writing-documentation" title="Permalink to this headline">¶</a></h3>
<p>The documentation itself is written in the reStructuredText (ReST) format, and
Sphinx defines additional tags to support features like cross-referencing.</p>
<p>The ReST format itself is organized around documents mostly being readable
plaintext documents. You should generally be able to write new documentation
easily just by following the style of the existing documentation.</p>
<p>If you want to understand the formatting of the documents more, the best place
to start is Sphinx’s own <a class="reference external" href="http://sphinx.pocoo.org/rest.html">ReST Primer</a>.</p>
</div>
</div>
<div class="section" id="learning-more">
<h2>Learning More<a class="headerlink" href="#learning-more" title="Permalink to this headline">¶</a></h2>
<p>If you want to learn more about the Sphinx system, the best place to start is
the Sphinx documentation itself, available <a class="reference external" href="http://sphinx.pocoo.org/contents.html">here</a>.</p>
</div>
<div class="section" id="installing-sphinx-in-a-virtual-environment">
<span id="installing-sphinx-in-a-venv"></span><h2>Installing Sphinx in a Virtual Environment<a class="headerlink" href="#installing-sphinx-in-a-virtual-environment" title="Permalink to this headline">¶</a></h2>
<p>Most Python developers prefer to work with tools inside a <em>virtualenv</em> (virtual
environment) instance, which functions as an application sandbox. This avoids
polluting your system installation with different packages used by various
projects (and ensures that dependencies for different packages don’t conflict
with one another). Of course, you need to first have the virtualenv software
itself which generally would be installed at the system level:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo easy_install virtualenv
</pre></div>
</div>
<p>but after that you no longer need to install additional packages in the system
directories.</p>
<p>Once you have the <em>virtualenv</em> tool itself installed, you can create a
virtualenv for Sphinx using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ virtualenv ~/my-sphinx-install
New python executable in /Users/dummy/my-sphinx-install/bin/python
Installing setuptools............done.
Installing pip...............done.
$ ~/my-sphinx-install/bin/easy_install sphinx
... install messages here ...
</pre></div>
</div>
<p>and from now on you can “activate” the <em>virtualenv</em> using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ source ~/my-sphinx-install/bin/activate
</pre></div>
</div>
<p>which will change your PATH to ensure the sphinx-build tool from inside the
virtual environment will be used. See the <a class="reference external" href="http://www.virtualenv.org/en/latest/index.html">virtualenv website</a> for more information on using
virtual environments.</p>
</div>
</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="WebAssembly.html" title="WebAssembly lld port"
>next</a> |</li>
<li class="right" >
<a href="open_projects.html" title="Open Projects"
>previous</a> |</li>
<li><a href="index.html">lld Home</a> | </li>
<li class="nav-item nav-item-1"><a href="AtomLLD.html" >ATOM-based lld</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2020, LLVM Project.
Last updated on 2020-02-14.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
</div>
</body>
</html>