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
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
|
<!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 with Paver — Paver 1.2.1 documentation</title>
<link rel="stylesheet" href="_static/default.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.2.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="top" title="Paver 1.2.1 documentation" href="index.html" />
<link rel="next" title="pavement.py in depth" href="pavement.html" />
<link rel="prev" title="Paver’s Features" href="features.html" />
</head>
<body>
<div class="related">
<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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="pavement.html" title="pavement.py in depth"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="features.html" title="Paver’s Features"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Paver 1.2.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="getting-started-with-paver">
<span id="gettingstarted"></span><h1>Getting Started with Paver<a class="headerlink" href="#getting-started-with-paver" title="Permalink to this headline">¶</a></h1>
<p>Often, the easiest way to get going with a new tool is to see an example
in action, so that’s how we’ll get started with Paver. In the Paver
distribution, there are samples under docs/samples. The Getting
Started samples are in the “started” directory under there.</p>
<div class="section" id="the-old-way">
<h2>The Old Way<a class="headerlink" href="#the-old-way" title="Permalink to this headline">¶</a></h2>
<p>Our first sample is called “The Old Way” (and it’s in the
docs/samples/started/oldway directory). It’s a fairly typical project
with one Python package and some docs, and we want to be able to
distribute it.</p>
<p>Python’s <a class="reference external" href="http://docs.python.org/dist/dist.html">distutils</a> makes it easy indeed to create a distributable
package. We create a setup.py file that looks like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#<== include('started/oldway/setup.py')==></span>
<span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">"TheOldWay"</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">'oldway'</span><span class="p">],</span>
<span class="n">version</span><span class="o">=</span><span class="s">"1.0"</span><span class="p">,</span>
<span class="n">url</span><span class="o">=</span><span class="s">"http://www.blueskyonmars.com/"</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s">"Kevin Dangoor"</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s">"dangoor@gmail.com"</span>
<span class="p">)</span>
<span class="c">#<==end==></span>
</pre></div>
</div>
<p>With that simple setup script, you can run:</p>
<div class="highlight-python"><pre>python setup.py sdist</pre>
</div>
<p>to build a source distribution:</p>
<div class="highlight-python"><pre># <==
# sh('cd docs/samples/started/oldway; python setup.py sdist',
# insert_output=False)
# sh('ls -l docs/samples/started/oldway/dist')
# ==>
celkem 4
-rw-r--r-- 1 almad almad 637 2.en 20.44 TheOldWay-1.0.tar.gz
# <==end==></pre>
</div>
<p>Then your users can run the familiar:</p>
<div class="highlight-python"><pre>python setup.py install</pre>
</div>
<p>to install the package, or use setuptools’ even easier:</p>
<div class="highlight-python"><pre>easy_install "TheOldWay"</pre>
</div>
<p>for packages that are up on the Python Package Index.</p>
<div class="section" id="the-old-way-s-docs">
<h3>The Old Way’s Docs<a class="headerlink" href="#the-old-way-s-docs" title="Permalink to this headline">¶</a></h3>
<p>The Old Way project is at least a bit modern in that it uses <a class="reference external" href="http://sphinx.pocoo.org">Sphinx</a> for documentation. When you use sphinx-quickstart to get going with your
docs, Sphinx will give you a Makefile that you can run to generate
your HTML docs. So, generating the HTML docs is easy:</p>
<div class="highlight-python"><pre>make html</pre>
</div>
<p>Except, in this project (as in Paver itself), we want to include the
HTML files in a docs directory in the package for presenting help to
the users. We end up creating a shell script to do this:</p>
<div class="highlight-python"><pre># <== include("started/oldway/builddocs.sh")==>
cd docs
make html
cd ..
rm -rf oldway/docs
mv docs/_build/html oldway/docs
# <==end==></pre>
</div>
<p>Of course, creating a script like this means that we have to actually
remember to run it. We could change this script to “buildsdist.sh”
and add a <tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">sdist</span></tt> to the end of the file. But,
wouldn’t it be nicer if we could just use <tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">sdist</span></tt>
directly?</p>
<p>You can <a class="reference external" href="http://docs.python.org/dist/node84.html">create new distutils commands</a>, but do you really want to
drop stuff like that in the distutils/command package in your
Python library directory? And how would you call the sdist command
anyway? <a class="reference external" href="http://peak.telecommunity.com/DevCenter/setuptools">setuptools</a> helps, but it still requires setting up a module
and entry point for this collection of commands.</p>
</div>
<div class="section" id="work-with-me-here">
<h3>Work with me here<a class="headerlink" href="#work-with-me-here" title="Permalink to this headline">¶</a></h3>
<p>I just <cite>know</cite> there are some people reading this and thinking
“man, what a contrived example!”. Building, packaging, distributing
and deploying of projects is quite custom for every project.
Part of the point of Paver is to make it easy to handle whatever
weird requirements arise in your project. This example may seem
contrived, but it should give you an idea of how easy Paver
makes it to get your tasks done.</p>
</div>
</div>
<div class="section" id="the-new-way">
<h2>The New Way<a class="headerlink" href="#the-new-way" title="Permalink to this headline">¶</a></h2>
<p>Let’s bring in Paver now to clean up our scripting a bit. Converting
a project to use Paver is really, really simple. Recall the setup
function from our Old Way setup.py:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include("started/oldway/setup.py", "setup")==></span>
<span class="n">setup</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">"TheOldWay"</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">'oldway'</span><span class="p">],</span>
<span class="n">version</span><span class="o">=</span><span class="s">"1.0"</span><span class="p">,</span>
<span class="n">url</span><span class="o">=</span><span class="s">"http://www.blueskyonmars.com/"</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s">"Kevin Dangoor"</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s">"dangoor@gmail.com"</span>
<span class="p">)</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<div class="section" id="id1">
<h3>Getting Started with Paver<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<p>setup.py is a standard Python script. It’s just called setup.py
as a convention. Paver works a bit more like Make or Rake.
To use Paver, you run <tt class="docutils literal"><span class="pre">paver</span> <span class="pre"><taskname></span></tt> and the paver
command will look for a pavement.py file in the current directory.
pavement.py is a standard Python module. A typical pavement will
import from paver.easy to get a bunch of convenience functions
and objects and then import other modules that include useful
tasks:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'imports')==></span>
<span class="kn">from</span> <span class="nn">paver.easy</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">import</span> <span class="nn">paver.doctools</span>
<span class="kn">from</span> <span class="nn">paver.setuputils</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>Converting from setup.py to pavement.py is easy. Paver provides
a special <tt class="docutils literal"><span class="pre">options</span></tt> object that holds all of your build options.
<tt class="docutils literal"><span class="pre">options</span></tt> is just a dictionary that allows attribute-style
access and has some special searching abilities. The options
for distutils operations are stored in a <tt class="docutils literal"><span class="pre">setup</span></tt> section of the
options. And, as a convenience, Paver provides a setup function
that sets the values in that options section (and goes a step
further, by making all of the distutils/setuptools commands
available as Paver tasks). Here’s what the conversion looks like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'setup')==></span>
<span class="n">setup</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">"TheNewWay"</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">'newway'</span><span class="p">],</span>
<span class="n">version</span><span class="o">=</span><span class="s">"1.0"</span><span class="p">,</span>
<span class="n">url</span><span class="o">=</span><span class="s">"http://www.blueskyonmars.com/"</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s">"Kevin Dangoor"</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s">"dangoor@gmail.com"</span>
<span class="p">)</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
</div>
<div class="section" id="paver-is-compatible-with-distutils">
<h3>Paver is compatible with distutils<a class="headerlink" href="#paver-is-compatible-with-distutils" title="Permalink to this headline">¶</a></h3>
<p>Choosing to use Paver does not mean giving up on distutils or
setuptools. Paver lets you continue to use distutils and setuptools
commands. When you import a module that has Paver tasks in it,
those tasks automatically become available for running. If you
want access to distutils and setuptools commands as well, you can either
use the <tt class="docutils literal"><span class="pre">paver.setuputils.setup</span></tt> function as described
above, or call <tt class="docutils literal"><span class="pre">paver.setuputils.install_distutils_tasks()</span></tt>.</p>
<p>We can see this in action by looking at <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">help</span></tt>:</p>
<div class="highlight-python"><pre># <== sh('cd docs/samples/started/newway; paver help')==>
---> paver.tasks.help
Usage: paver [global options] taskname [task options] [taskname [taskoptions]]
Options:
--version show program's version number and exit
-n, --dry-run don't actually do anything
-v, --verbose display all logging output
-q, --quiet display only errors
-i, --interactive enable prompting
-f FILE, --file=FILE read tasks from FILE [pavement.py]
-h, --help display this help information
--propagate-traceback
propagate traceback, do not hide it under
BuildFailure(for debugging)
Tasks from paver.doctools:
doc_clean - Clean (delete) the built docs
Tasks from setuptools.command:
build_py - "build" pure Python modules (copy to build directory)
Tasks from paver.misctasks:
paverdocs - Open your web browser and display Paver's documentation.
Tasks from setuptools.command:
test - run unit tests after in-place build
Tasks from paver.doctools:
cog - Runs the cog code generator against the files matching your
specification
Tasks from setuptools.command:
bdist_rpm - create an RPM distribution
Tasks from paver.doctools:
uncog - Remove the Cog generated code from files
Tasks from setuptools.command:
install_egg_info - Install an .egg-info directory for the package
Tasks from distutils.command:
build_clib - build C/C++ libraries used by Python extensions
Tasks from setuptools.command:
saveopts - save supplied options to setup.cfg or other config file
Tasks from distutils.command:
build_scripts - "build" scripts (copy and fixup #! line)
Tasks from paver.misctasks:
minilib - Create a Paver mini library that contains enough for a simple
pavement.py to be installed using a generated setup.py
Tasks from distutils.command:
bdist_dumb - create a "dumb" built distribution
Tasks from paver.misctasks:
generate_setup - Generates a setup.py file that uses paver behind the scenes
Tasks from setuptools.command:
egg_info - create a distribution's .egg-info directory
Tasks from sphinx_pypi_upload:
upload_sphinx - Upload Sphinx documentation to PyPI
Tasks from setuptools.command:
bdist_egg - create an "egg" distribution
Tasks from nose.commands:
nosetests - Run unit tests using nosetests
Tasks from distutils.command:
check - perform some checks on the package
Tasks from setuptools.command:
register - register the distribution with the Python package index
Tasks from paver.tasks:
help - This help display.
Tasks from setuptools.command:
alias - define a shortcut to invoke one or more commands
rotate - delete older distributions, keeping N newest files
Tasks from paver.doctools:
html - Build HTML documentation using Sphinx
Tasks from setuptools.command:
easy_install - Find/get/install Python packages
Tasks from distutils.command:
install_headers - install C/C++ header files
install_data - install data files
Tasks from setuptools.command:
build_ext - build C/C++ extensions (compile/link to build directory)
develop - install package in 'development mode'
Tasks from distutils.command:
build - build everything needed to install
Tasks from sphinx.setup_command:
build_sphinx - Build Sphinx documentation
Tasks from setuptools.command:
install_lib - install all Python modules (extensions and pure Python)
bdist_wininst - create an executable installer for MS Windows
install_scripts - install scripts (Python or otherwise)
setopt - set an option in setup.cfg or another config file
Tasks from distutils.command:
upload - upload binary package to PyPI
clean - clean up temporary files from 'build' command
Tasks from setuptools.command:
sdist - create a source distribution (tarball, zip file, etc.)
Tasks from distutils.command:
bdist - create a built (binary) distribution
Tasks from setuptools.command:
install - install everything from build directory
Tasks from pavement:
sdist - Overrides sdist to make sure that our setup.py is generated.
html - Build the docs and put them into our package.
deploy - Deploy the HTML to the server.
# <==end==></pre>
</div>
<p>That command is listing all of the available tasks, and you can see
near the top there are tasks from distutils.command. All of the
standard distutils commands are available.</p>
<p>There’s one more thing we need to do before our Python package
is properly redistributable: tell distutils about our special files.
We can do that with a simple MANIFEST.in:</p>
<div class="highlight-python"><pre># <== include('started/newway/MANIFEST.in')==>
include setup.py
include pavement.py
include paver-minilib.zip
# <==end==></pre>
</div>
<p>With that, we can run <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">sdist</span></tt> and end up with the
equivalent output file:</p>
<div class="highlight-python"><pre># <==
# sh('cd docs/samples/started/newway; paver sdist',
# insert_output=False)
# sh('ls -l docs/samples/started/newway/dist')
# ==>
celkem 48
-rw-r--r-- 1 almad almad 45726 2.en 20.44 TheNewWay-1.0.tar.gz
# <==end==></pre>
</div>
<p>It also means that users of The New Way can also run <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">install</span></tt>
to install the package on their system. Neat.</p>
</div>
<div class="section" id="but-people-are-used-to-setup-py">
<h3>But people are used to setup.py!<a class="headerlink" href="#but-people-are-used-to-setup-py" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></tt> has been around a long time. And while
you could certainly put a README file in your package telling
people to run <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">install</span></tt>, we all know that no one actually
reads docs. (Hey, thanks for taking the time to read this!)</p>
<p>No worries, though. You can run <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">generate_setup</span></tt> to get a
setup.py file that you can ship in your tarball. Then your users
can run <tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></tt> just like they’re used to,
and Paver will take over.</p>
</div>
<div class="section" id="but-people-don-t-have-paver-yet">
<h3>But people don’t have Paver yet!<a class="headerlink" href="#but-people-don-t-have-paver-yet" title="Permalink to this headline">¶</a></h3>
<p>There are millions of Python installations that don’t have Paver yet,
but have Python and distutils. How can they run a Paver-based install?</p>
<p>Easy, you just run <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">minilib</span></tt> and you will get a file called
paver-minilib.zip. That file has enough of Paver to allow someone
to install most projects. The Paver-generated setup.py knows to look
for that file and use it if it sees it.</p>
<p>Worried about bloating your package? The paver-minilib is not large:</p>
<div class="highlight-python"><pre># <==
# sh('cd docs/samples/started/newway ; paver minilib',
# insert_output=False)
# sh('ls -l docs/samples/started/newway/paver-minilib.zip')
# ==>
-rw-r--r-- 1 almad almad 44375 2.en 20.44 docs/samples/started/newway/paver-minilib.zip
# <==end==></pre>
</div>
<p>Paver itself is bootstrapped with a generated setup file and a
paver-minilib.</p>
</div>
<div class="section" id="hey-didn-t-you-just-create-more-work-for-me">
<h3>Hey! Didn’t you just create more work for me?<a class="headerlink" href="#hey-didn-t-you-just-create-more-work-for-me" title="Permalink to this headline">¶</a></h3>
<p>You might have noticed that we now have three commands to run in
order to get a proper distribution for The New Way. Well, you can
actually run them all at once: <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">generate_setup</span> <span class="pre">minilib</span> <span class="pre">sdist</span></tt>.
That’s not terrible, but it’s also not great. You don’t want to
end up with a broken distribution just because you forgot one of
the tasks.</p>
<p>By design, one of the easiest things to do in Paver is to extend
the behavior of an existing “task”, and that includes distutils
commands. All we need to do is create a new sdist task in our
pavement.py:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'sdist')==></span>
<span class="nd">@task</span>
<span class="nd">@needs</span><span class="p">(</span><span class="s">'generate_setup'</span><span class="p">,</span> <span class="s">'minilib'</span><span class="p">,</span> <span class="s">'setuptools.command.sdist'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">sdist</span><span class="p">():</span>
<span class="sd">"""Overrides sdist to make sure that our setup.py is generated."""</span>
<span class="k">pass</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>The @task decorator just tells Paver that this is a task and not just
a function. The @needs decorator specifies other tasks that should
run before this one. You can also use the <cite>call_task(taskname)</cite>
function within your task if you wish. The function name determines
the name of the task. The docstring is what shows up in Paver’s
help output.</p>
<p>With that task in our pavement.py, <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">sdist</span></tt> is all it takes
to build a source distribution after generating a setup file
and minilib.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you are depending on distutils task (via @needs), you have to call <tt class="docutils literal"><span class="pre">setup()</span></tt> before task is defined.
Under the hood, <tt class="docutils literal"><span class="pre">setup</span></tt> call installs distutils/setupsools task and make them available, so do not make it conditional.</p>
</div>
</div>
<div class="section" id="tackling-the-docs">
<h3>Tackling the Docs<a class="headerlink" href="#tackling-the-docs" title="Permalink to this headline">¶</a></h3>
<p>Until the tools themselves provide tasks and functions that make
creating pavements easier, Paver’s Standard Library will include
a collection of modules that help out for commonly used tools.
Sphinx is one package for which Paver has built-in support.</p>
<p>To use Paver’s Sphinx support, you need to have Sphinx installed
and, in your pavement.py, <tt class="docutils literal"><span class="pre">import</span> <span class="pre">paver.doctools</span></tt>. Just performing
the import will make the doctools-related tasks available.
<tt class="docutils literal"><span class="pre">paver</span> <span class="pre">help</span> <span class="pre">html</span></tt> will tell us how to use the html command:</p>
<div class="highlight-python"><pre># <== sh('paver help paver.doctools.html')==>
---> paver.tasks.help
paver.doctools.html
-------------------
Usage: paver paver.doctools.html [options]
Options:
-h, --help display this help information
Build HTML documentation using Sphinx. This uses the following
options in a "sphinx" section of the options.
docroot
the root under which Sphinx will be working. Default: docs
builddir
directory under the docroot where the resulting files are put.
default: build
sourcedir
directory under the docroot for the source files
default: (empty string)
# <==end==></pre>
</div>
<p>According to that, we’ll need to set the builddir setting, since we’re
using a builddir called “_build”. Let’s add this to our pavement.py:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'sphinx')==></span>
<span class="n">options</span><span class="p">(</span>
<span class="n">sphinx</span><span class="o">=</span><span class="n">Bunch</span><span class="p">(</span>
<span class="n">builddir</span><span class="o">=</span><span class="s">"_build"</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>And with that, <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">html</span></tt> is now equivalent to <tt class="docutils literal"><span class="pre">make</span> <span class="pre">html</span></tt> using
the Makefile that Sphinx gave us.</p>
</div>
<div class="section" id="getting-rid-of-our-docs-shell-script">
<h3>Getting rid of our docs shell script<a class="headerlink" href="#getting-rid-of-our-docs-shell-script" title="Permalink to this headline">¶</a></h3>
<p>You may remember that shell script we had for moving our generated
docs to the right place:</p>
<div class="highlight-python"><pre># <== include('started/oldway/builddocs.sh')==>
cd docs
make html
cd ..
rm -rf oldway/docs
mv docs/_build/html oldway/docs
# <==end==></pre>
</div>
<p>Ideally, we’d want this to happen whenever we generate the docs.
We’ve already seen how to override tasks, so let’s try that out
here:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'html')==></span>
<span class="nd">@task</span>
<span class="nd">@needs</span><span class="p">(</span><span class="s">'paver.doctools.html'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">html</span><span class="p">(</span><span class="n">options</span><span class="p">):</span>
<span class="sd">"""Build the docs and put them into our package."""</span>
<span class="n">destdir</span> <span class="o">=</span> <span class="n">path</span><span class="p">(</span><span class="s">'newway/docs'</span><span class="p">)</span>
<span class="n">destdir</span><span class="o">.</span><span class="n">rmtree</span><span class="p">()</span>
<span class="n">builtdocs</span> <span class="o">=</span> <span class="n">path</span><span class="p">(</span><span class="s">"docs"</span><span class="p">)</span> <span class="o">/</span> <span class="n">options</span><span class="o">.</span><span class="n">builddir</span> <span class="o">/</span> <span class="s">"html"</span>
<span class="n">builtdocs</span><span class="o">.</span><span class="n">move</span><span class="p">(</span><span class="n">destdir</span><span class="p">)</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>There are a handful of interesting things in here. The equivalent of
‘make html’ is the @needs(‘paver.doctools.html’), since that’s
the task we’re overriding.</p>
<p>Inside our task, we’re using “path”. This is a customized
version of Jason Orendorff’s path module. All kinds of file
and directory operations become super-simple using this module.</p>
<p>We start by deleting our destination directory, since we’ll be copying
new generated files into that spot. Next, we look at the built
docs directory that we’ll be moving:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'html.builtdocs')==></span>
<span class="n">builtdocs</span> <span class="o">=</span> <span class="n">path</span><span class="p">(</span><span class="s">"docs"</span><span class="p">)</span> <span class="o">/</span> <span class="n">options</span><span class="o">.</span><span class="n">builddir</span> <span class="o">/</span> <span class="s">"html"</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>One cool thing about path objects is that you can use the natural
and comfortable ‘/’ operator to build up your paths.</p>
<p>The next thing we see here is the accessing of options. The
options object is available to your tasks. It’s basically a dictionary
that offers attribute-style access and can search for variables
(which is why you can type options.builddir instead of
the longer options.sphinx.builddir). That property of options is
also convenient for being able to share properties between sections.</p>
<p>And with that, we eliminate the shell script as a separate file.</p>
</div>
<div class="section" id="fixing-another-wart-in-the-old-way">
<h3>Fixing another wart in The Old Way<a class="headerlink" href="#fixing-another-wart-in-the-old-way" title="Permalink to this headline">¶</a></h3>
<p>In the documentation for The Old Way, we actually included the
function body directly in the docs. But, we had to cut and paste
it there. Sphinx does offer a way to include an external file
in your documentation. Paver includes a better way.</p>
<p>There are a couple of parts to the documentation problem:</p>
<ol class="arabic simple">
<li>It’s good to have your code in separate files from your docs
so that the code can be complete, runnable and, above all,
testable programs so that you can be sure that everything works.</li>
<li>You want your writing and the samples included with your writing
to stand up as reasonable, coherent documents. Python’s doctest
style does not always lend itself to coherent documents.</li>
<li>It’s nice to have the code sample that you’re writing about
included inline with the documents as you’re writing them.
It’s easier to write when you can easily see what you’re
writing about.</li>
</ol>
<p>#1 and #3 sound mutually exclusive, but they’re not. Paver has a
two part strategy to solve this problem. Let’s look at part of the index.rst
document file to see the first part:</p>
<div class="highlight-python"><pre># <== include("started/newway/docs/index.rst", "mainpart")==>
Welcome to The New Way's documentation!
=======================================
This is the Paver way of doing things. The key functionality here
is in this powerful piece of code, which I will `include` here in its entirety
so that you can bask in its power::
# [[[cog include("newway/thecode.py", "code")]]]
# [[[end]]]
# <==end==></pre>
</div>
<p>In The New Way’s index.rst, you can see the same mechanism being used that
is used in this Getting Started guide. Paver includes Ned Batchelder’s
<a class="reference external" href="http://nedbatchelder.com/code/cog/">Cog</a> package. Cog lets you drop snippets of Python into a file and have
those snippets generate stuff that goes into the file. Unlike a template
language, Cog is designed so that you can leave the markers in and
regenerate as often as you need to. With a template language, you have
the template and the finalized output, but not a file that has both.</p>
<p>So, as I’m writing this Getting Started document, I can glance up and see
the index.rst contents right inline. You’ll notice The #[[[cog part in there
is calling an include() function. This is the second part offered by
Paver. Paver lets you specify an “includedir” for use with Cog.
This lets you include files relative to that directory. And, critically,
it also lets you mark off sections of those files so that you can
easily include just the part you want. In the example above, we’re picking
up the ‘code’ section of the newway/thecode.py file. Let’s take a look
at that file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== sh("cat docs/samples/started/newway/newway/thecode.py") ==></span>
<span class="sd">"""This is our powerful, code-filled, new-fangled module."""</span>
<span class="c"># [[[section code]]]</span>
<span class="k">def</span> <span class="nf">powerful_function_and_new_too</span><span class="p">():</span>
<span class="sd">"""This is powerful stuff, and it's new."""</span>
<span class="k">return</span> <span class="mi">2</span><span class="o">*</span><span class="mi">1</span>
<span class="c"># [[[endsection]]]</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>Paver has a Cog-like syntax for defining named sections. So, you just
use the <tt class="docutils literal"><span class="pre">include</span></tt> function with the relative filename and the section
you want, and it will be included. Sections can even be nested (and
you refer to nested sections using familiar dotted notation).</p>
</div>
<div class="section" id="bonus-deployment-example">
<h3>Bonus Deployment Example<a class="headerlink" href="#bonus-deployment-example" title="Permalink to this headline">¶</a></h3>
<p>pavements are just standard Python. The syntax for looping and things
like that are just what you’re used to. The options are standard Python
so they can contain lists and other objects. Need to deploy to
multiple hosts? Just put the hosts in the options and loop over them.</p>
<p>Let’s say we want to deploy The New Way project’s HTML files to a
couple of servers. This is similar to what I do for Paver itself, though
I only have one server. First, we’ll set up some variables to use for
our deploy task:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include('started/newway/pavement.py', 'deployoptions')==></span>
<span class="n">options</span><span class="p">(</span>
<span class="n">deploy</span> <span class="o">=</span> <span class="n">Bunch</span><span class="p">(</span>
<span class="n">htmldir</span> <span class="o">=</span> <span class="n">path</span><span class="p">(</span><span class="s">'newway/docs'</span><span class="p">),</span>
<span class="n">hosts</span> <span class="o">=</span> <span class="p">[</span><span class="s">'host1.hostymost.com'</span><span class="p">,</span> <span class="s">'host2.hostymost.com'</span><span class="p">],</span>
<span class="n">hostpath</span> <span class="o">=</span> <span class="s">'sites/newway'</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>As you can see, we can put whatever kinds of objects we wish into
the options. Now for the deploy task itself:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># <== include("started/newway/pavement.py", "deploy")==></span>
<span class="nd">@task</span>
<span class="nd">@cmdopts</span><span class="p">([</span>
<span class="p">(</span><span class="s">'username='</span><span class="p">,</span> <span class="s">'u'</span><span class="p">,</span> <span class="s">'Username to use when logging in to the servers'</span><span class="p">)</span>
<span class="p">])</span>
<span class="k">def</span> <span class="nf">deploy</span><span class="p">(</span><span class="n">options</span><span class="p">):</span>
<span class="sd">"""Deploy the HTML to the server."""</span>
<span class="k">for</span> <span class="n">host</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">hosts</span><span class="p">:</span>
<span class="n">sh</span><span class="p">(</span><span class="s">"rsync -avz -e ssh </span><span class="si">%s</span><span class="s">/ </span><span class="si">%s</span><span class="s">@</span><span class="si">%s</span><span class="s">:</span><span class="si">%s</span><span class="s">/"</span> <span class="o">%</span> <span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">htmldir</span><span class="p">,</span>
<span class="n">options</span><span class="o">.</span><span class="n">username</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">hostpath</span><span class="p">))</span>
<span class="c"># <==end==></span>
</pre></div>
</div>
<p>You’ll notice the new “cmdopts” decorator. Let’s say that you have
sensitive information like a password that you don’t want to include
in your pavement. You can easily make it a command line option for that
task using cmdopts. options.deploy.username will be set to whatever
the user enters on the command line.</p>
<p>It’s also worth noting that when looking up options, Paver gives
priority to options in a section with the same name as the task. So,
options.username will prefer options.deploy.username even if there
is a username in another section.</p>
<p>Our deploy task uses a simple for loop to run an rsync command
for each host. Let’s do a dry run providing a username to see
what the commands will be:</p>
<div class="highlight-python"><pre># <== sh("cd docs/samples/started/newway; paver -n deploy -u kevin")==>
---> pavement.deploy
rsync -avz -e ssh newway/docs/ kevin@host1.hostymost.com:sites/newway/
rsync -avz -e ssh newway/docs/ kevin@host2.hostymost.com:sites/newway/
# <==end==></pre>
</div>
</div>
<div class="section" id="where-to-go-from-here">
<h3>Where to go from here<a class="headerlink" href="#where-to-go-from-here" title="Permalink to this headline">¶</a></h3>
<p>The first thing to do is to just get started using Paver. As you’ve seen
above, it’s easy to get Paver into your workflow, even with existing
projects.</p>
<p>Use the <tt class="docutils literal"><span class="pre">paver</span> <span class="pre">help</span></tt> command.</p>
<p>If you really want more detail now, you’ll want to read more about
<a class="reference internal" href="pavement.html#pavement"><em>pavement files</em></a> and the
<a class="reference internal" href="paverstdlib.html#stdlib"><em>Paver Standard Library</em></a>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Getting Started with Paver</a><ul>
<li><a class="reference internal" href="#the-old-way">The Old Way</a><ul>
<li><a class="reference internal" href="#the-old-way-s-docs">The Old Way’s Docs</a></li>
<li><a class="reference internal" href="#work-with-me-here">Work with me here</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-new-way">The New Way</a><ul>
<li><a class="reference internal" href="#id1">Getting Started with Paver</a></li>
<li><a class="reference internal" href="#paver-is-compatible-with-distutils">Paver is compatible with distutils</a></li>
<li><a class="reference internal" href="#but-people-are-used-to-setup-py">But people are used to setup.py!</a></li>
<li><a class="reference internal" href="#but-people-don-t-have-paver-yet">But people don’t have Paver yet!</a></li>
<li><a class="reference internal" href="#hey-didn-t-you-just-create-more-work-for-me">Hey! Didn’t you just create more work for me?</a></li>
<li><a class="reference internal" href="#tackling-the-docs">Tackling the Docs</a></li>
<li><a class="reference internal" href="#getting-rid-of-our-docs-shell-script">Getting rid of our docs shell script</a></li>
<li><a class="reference internal" href="#fixing-another-wart-in-the-old-way">Fixing another wart in The Old Way</a></li>
<li><a class="reference internal" href="#bonus-deployment-example">Bonus Deployment Example</a></li>
<li><a class="reference internal" href="#where-to-go-from-here">Where to go from here</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="features.html"
title="previous chapter">Paver’s Features</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pavement.html"
title="next chapter">pavement.py in depth</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/getting_started.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="pavement.html" title="pavement.py in depth"
>next</a> |</li>
<li class="right" >
<a href="features.html" title="Paver’s Features"
>previous</a> |</li>
<li><a href="index.html">Paver 1.2.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008, SitePen, Inc..
Last updated on Jun 02, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div>
</body>
</html>
|
