{{ message }}
-
Notifications
You must be signed in to change notification settings - Fork 62
Expand file tree
/
Copy pathgetting_started.html
More file actions
222 lines (205 loc) · 14.3 KB
/
Copy pathgetting_started.html
File metadata and controls
222 lines (205 loc) · 14.3 KB
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
<!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="Content-Type" content="text/html; charset=utf-8" />
<title>Getting started — sampledoc 1.0 documentation</title>
<link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Customizing the look and feel of the site" href="custom_look.html" />
<link rel="prev" title="sampledoc tutorial" href="index.html" />
</head>
<body role="document">
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><h1 style="font-size: 3em;">Sampledoc</h1></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="custom_look.html" title="Customizing the look and feel of the site"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="sampledoc tutorial"
accesskey="P">previous</a> |</li>
<li><a href="index.html">home</a>| </li>
<li><a href="search.html">search</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="#">Getting started</a><ul>
<li><a class="reference internal" href="#installing-your-doc-directory">Installing your doc directory</a><ul>
<li><a class="reference internal" href="#fetching-the-data">Fetching the data</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">sampledoc tutorial</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="custom_look.html"
title="next chapter">Customizing the look and feel of the site</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/getting_started.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</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="getting-started">
<span id="id1"></span><h1>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>
<div class="section" id="installing-your-doc-directory">
<span id="installing-docdir"></span><h2>Installing your doc directory<a class="headerlink" href="#installing-your-doc-directory" title="Permalink to this headline">¶</a></h2>
<p>You may already have sphinx <a class="reference external" href="http://sphinx.pocoo.org/">sphinx</a>
installed – you can check by doing:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">c</span> <span class="s1">'import sphinx'</span>
</pre></div>
</div>
<p>If that fails grab the latest version of and install it with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">></span> <span class="n">sudo</span> <span class="n">easy_install</span> <span class="o">-</span><span class="n">U</span> <span class="n">Sphinx</span>
</pre></div>
</div>
<p>Now you are ready to build a template for your docs, using
sphinx-quickstart:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">></span> <span class="n">sphinx</span><span class="o">-</span><span class="n">quickstart</span>
</pre></div>
</div>
<p>accepting most of the defaults. I choose “sampledoc” as the name of my
project. cd into your new directory and check the contents:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">ls</span>
<span class="n">Makefile</span> <span class="n">_static</span> <span class="n">conf</span><span class="o">.</span><span class="n">py</span>
<span class="n">_build</span> <span class="n">_templates</span> <span class="n">index</span><span class="o">.</span><span class="n">rst</span>
</pre></div>
</div>
<p>The index.rst is the master ReST for your project, but before adding
anything, let’s see if we can build some html:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>If you now point your browser to <code class="file docutils literal"><span class="pre">_build/html/index.html</span></code>, you
should see a basic sphinx site.</p>
<img alt="_images/basic_screenshot.png" src="_images/basic_screenshot.png" />
<div class="section" id="fetching-the-data">
<span id="id2"></span><h3>Fetching the data<a class="headerlink" href="#fetching-the-data" title="Permalink to this headline">¶</a></h3>
<p>Now we will start to customize out docs. Grab a couple of files from
the <a class="reference external" href="https://github.com/matplotlib/sampledoc">web site</a>
or git. You will need <code class="file docutils literal"><span class="pre">getting_started.rst</span></code> and
<code class="file docutils literal"><span class="pre">_static/basic_screenshot.png</span></code>. All of the files live in the
“completed” version of this tutorial, but since this is a tutorial,
we’ll just grab them one at a time, so you can learn what needs to be
changed where. Since we have more files to come, I’m going to grab
the whole git directory and just copy the files I need over for now.
First, I’ll cd up back into the directory containing my project, check
out the “finished” product from git, and then copy in just the files I
need into my <code class="file docutils literal"><span class="pre">sampledoc</span></code> directory:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">pwd</span>
<span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">jdhunter</span><span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">cd</span> <span class="o">..</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">></span> <span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">matplotlib</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">.</span><span class="n">git</span> <span class="n">tutorial</span>
<span class="n">Cloning</span> <span class="n">into</span> <span class="s1">'tutorial'</span><span class="o">...</span>
<span class="n">remote</span><span class="p">:</span> <span class="n">Counting</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">87</span><span class="p">,</span> <span class="n">done</span><span class="o">.</span>
<span class="n">remote</span><span class="p">:</span> <span class="n">Compressing</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">100</span><span class="o">%</span> <span class="p">(</span><span class="mi">43</span><span class="o">/</span><span class="mi">43</span><span class="p">),</span> <span class="n">done</span><span class="o">.</span>
<span class="n">remote</span><span class="p">:</span> <span class="n">Total</span> <span class="mi">87</span> <span class="p">(</span><span class="n">delta</span> <span class="mi">45</span><span class="p">),</span> <span class="n">reused</span> <span class="mi">83</span> <span class="p">(</span><span class="n">delta</span> <span class="mi">41</span><span class="p">)</span>
<span class="n">Unpacking</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">100</span><span class="o">%</span> <span class="p">(</span><span class="mi">87</span><span class="o">/</span><span class="mi">87</span><span class="p">),</span> <span class="n">done</span><span class="o">.</span>
<span class="n">Checking</span> <span class="n">connectivity</span><span class="o">...</span> <span class="n">done</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">></span> <span class="n">cp</span> <span class="n">tutorial</span><span class="o">/</span><span class="n">getting_started</span><span class="o">.</span><span class="n">rst</span> <span class="n">sampledoc</span><span class="o">/</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">></span> <span class="n">cp</span> <span class="n">tutorial</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">basic_screenshot</span><span class="o">.</span><span class="n">png</span> <span class="n">sampledoc</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span>
</pre></div>
</div>
<p>The last step is to modify <code class="file docutils literal"><span class="pre">index.rst</span></code> to include the
<code class="file docutils literal"><span class="pre">getting_started.rst</span></code> file (be careful with the indentation, the
“g” in “getting_started” should line up with the ‘:’ in <code class="docutils literal"><span class="pre">:maxdepth</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Contents</span><span class="p">:</span>
<span class="o">..</span> <span class="n">toctree</span><span class="p">::</span>
<span class="p">:</span><span class="n">maxdepth</span><span class="p">:</span> <span class="mi">2</span>
<span class="n">getting_started</span><span class="o">.</span><span class="n">rst</span>
</pre></div>
</div>
<p>and then rebuild the docs:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">sampledoc</span>
<span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>When you reload the page by refreshing your browser pointing to
<code class="file docutils literal"><span class="pre">_build/html/index.html</span></code>, you should see a link to the
“Getting Started” docs, and in there this page with the screenshot.
<cite>Voila!</cite></p>
<p>Note we used the image directive to include to the screenshot above
with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">image</span><span class="p">::</span> <span class="n">_static</span><span class="o">/</span><span class="n">basic_screenshot</span><span class="o">.</span><span class="n">png</span>
</pre></div>
</div>
<p>Next we’ll customize the look and feel of our site to give it a logo,
some custom css, and update the navigation panels to look more like
the <a class="reference external" href="http://sphinx.pocoo.org/">sphinx</a> site itself – see
<a class="reference internal" href="custom_look.html#custom-look"><span class="std std-ref">Customizing the look and feel of the site</span></a>.</p>
</div>
</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="custom_look.html" title="Customizing the look and feel of the site"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="sampledoc tutorial"
>previous</a> |</li>
<li><a href="index.html">home</a>| </li>
<li><a href="search.html">search</a>| </li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009, John Hunter, Fernando Perez, Michael Droettboom.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.1.
</div>
</body>
</html>
You can’t perform that action at this time.