/usr/share/doc/rest2web/html/tutorial.html is in rest2web-doc 0.5.2~alpha+svn-r248-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 | <!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" lang="en" xml:lang="en">
<head>
<title>Introduction to rest2web</title>
<link rel="stylesheet" href="stylesheets/rest2web.css" type="text/css" />
<link rel="stylesheet" href="stylesheets/voidspace_docutils2.css" type="text/css" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="rest2web - build websites with Python and docutils." />
<meta name="author" content="Michael Foord" />
<meta name="copyright" content="© 2003-2006 Michael Foord, subject to BSD License" />
<meta name="keywords" content="rest2web - build websites with Python and docutils,
rest, restructured text, text, website, internet, web, net, web builder, site,
site builder, docutils, i18n, internationalization, templates, templating,
python, tutorial, introduction, beginners, site builder, website, basics, guide, basic guide" />
</head>
<body style="background: url(images/logos/img_background.gif) top center repeat-y;">
<div id="wrap">
<div id="header-section">
<a href="http://www.voidspace.org.uk/python/index.shtml" title="Voidspace"><img src="images/logos/header760.gif" alt="Voidspace"/></a>
<p align="center" class="headertitle"><span style="font-size:130%">rest2web:</span> Building Websites Across the Known Universe</p>
</div>
<div id="header">
<ul>
<li><a href="index.html">rest2web</a></li>
<li>></li>
<li>Tutorial</li>
</ul>
</div>
<table>
<tr>
<td><img src="images/logos/1.gif" width="1" height="1" alt="" /></td>
<!-- main content cell first, with rowspan=2 -->
<td valign="top" align="left" rowspan="2">
<div id="middle-column">
<a name="startcontent" id="startcontent"></a>
<div id="gallery">
<div class="document" id="introduction-to-rest2web">
<h1 class="title">Introduction to rest2web</h1>
<h2 class="subtitle" id="creating-a-website-with-rest2web">Creating a Website With rest2web</h2>
<div class="contents topic" id="rest2web-tutorial">
<p class="topic-title first">rest2web Tutorial</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id20">Introduction</a></li>
<li><a class="reference internal" href="#a-basic-site" id="id21">A Basic Site</a><ul>
<li><a class="reference internal" href="#the-config-file" id="id22">The Config File</a></li>
<li><a class="reference internal" href="#the-template-file" id="id23">The Template File</a></li>
<li><a class="reference internal" href="#the-index-file" id="id24">The Index File</a></li>
<li><a class="reference internal" href="#other-pages" id="id25">Other Pages</a></li>
<li><a class="reference internal" href="#subdirectories" id="id26">Subdirectories</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-an-example-site" id="id27">Creating an Example Site</a><ul>
<li><a class="reference internal" href="#config-file" id="id28">Config File</a></li>
<li><a class="reference internal" href="#html-template" id="id29">HTML Template</a><ul>
<li><a class="reference internal" href="#special-values" id="id30">Special Values</a><ul>
<li><a class="reference internal" href="#title" id="id31">title</a></li>
<li><a class="reference internal" href="#final-encoding" id="id32">final_encoding</a></li>
<li><a class="reference internal" href="#path-to-root" id="id33">path_to_root</a></li>
<li><a class="reference internal" href="#print-crumbs" id="id34">print_crumbs</a></li>
<li><a class="reference internal" href="#body" id="id35">body</a></li>
<li><a class="reference internal" href="#modtime" id="id36">modtime</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#the-index-page" id="id37">The Index Page</a><ul>
<li><a class="reference internal" href="#the-restindex" id="id38">The restindex</a></li>
<li><a class="reference internal" href="#the-content" id="id39">The Content</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id7" id="id40">Other Pages</a><ul>
<li><a class="reference internal" href="#rest-content" id="id41">reST Content</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id10" id="id42">Subdirectories</a></li>
</ul>
</li>
<li><a class="reference internal" href="#more-advanced-topics" id="id43">More Advanced Topics</a></li>
<li><a class="reference internal" href="#footnotes" id="id44">Footnotes</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id20">Introduction</a></h1>
<p><img src="images/paper.gif" alt="emoticon:paper" /> Creating a website with <strong>rest2web</strong> is easy. Looking at the
bewildering array of options in the <a class="reference external" href="restindex.html">restindex</a> can make it seem very complex.
In fact, you can build a simple website in a few minutues - using only a few
features. You can then add things as you need them. If you look in the source
files for the <a class="reference external" href="tutorial_site/index.html">example site</a> <a class="footnote-reference" href="#id11" id="id1">[1]</a>, you can see that most of the pages have
only two or three items in the <tt class="docutils literal"><span class="pre">restindex</span></tt>.</p>
<p>This tutorial explains the basics of creating a website - and shows you an
example.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This tutorial assumes you are basically familiar with <acronym title="HyperText Markup Language">HTML</acronym> and
creating/editing text files.</p>
</div>
</div>
<div class="section" id="a-basic-site">
<h1><a class="toc-backref" href="#id21">A Basic Site</a></h1>
<p>The principles of <strong>rest2web</strong> are simple. A rest2web site has at least the
following elements :</p>
<ol class="arabic simple">
<li><a class="reference external" href="config_file.html">Config file</a> - this tells rest2web where to read files from (the start
directory), and where to put the files it creates (the target directory).</li>
<li><a class="reference external" href="templating.html">template.txt</a> - This is the <acronym title="HyperText Markup Language">HTML</acronym> template for your website.</li>
<li><strong>index.txt</strong> - This is the source file (content) for your main index page.
Each directory <em>must</em> have this file.</li>
<li>Optionally other text files for your other pages.</li>
<li>Subdirectories with more content.</li>
</ol>
<p>We'll briefly look at these things, and then create a basic site.</p>
<div class="section" id="the-config-file">
<h2><a class="toc-backref" href="#id22">The Config File</a></h2>
<p><strong>rest2web</strong> goes through all the files in your source directory (and
subdirectories). It builds the contents, indexes, etc - puts them into the
templates, and then saves the results in the target directory.</p>
<p>So at the minimum, rest2web needs to know the source directory and target
directory. It gets these from the config file.</p>
<p>You tell <strong>rest2web</strong> the name of your config file at the command line :</p>
<pre class="literal-block">
python r2w.py config_file.ini
</pre>
<p>If you <em>don't</em> specify a config file, then rest2web will look for one called
<tt class="docutils literal"><span class="pre">r2w.ini</span></tt> in the current directory. On Windoze, this means you can just
double click on <em>r2w.py</em> and it will do it's magic.</p>
<p>There are several other options in the config file- but the source and target
directories are the two options you must specify for each site.</p>
<p>Look at the example <tt class="docutils literal"><span class="pre">r2w.ini</span></tt> that comes with rest2web, or the
<a class="reference external" href="config_file.html">Config file</a> page, for full details.</p>
</div>
<div class="section" id="the-template-file">
<h2><a class="toc-backref" href="#id23">The Template File</a></h2>
<p>The template file is the HTML framework for your website. Special values that
you put in your template determine where the content, title, and navigation
elements go.</p>
<p>The name <tt class="docutils literal"><span class="pre">template.txt</span></tt> is just the default filename. You can change the name
and location of this file through the <tt class="docutils literal"><span class="pre">restindex</span></tt>. You can also use more than
one template in your website.</p>
<p>If you are only using one template in your website (as many will) then you can
do this by just having one file (<tt class="docutils literal"><span class="pre">template.txt</span></tt>) in the top level of your
source directory.</p>
</div>
<div class="section" id="the-index-file">
<h2><a class="toc-backref" href="#id24">The Index File</a></h2>
<p>Every <em>directory</em> must have a file called <tt class="docutils literal"><span class="pre">index.txt</span></tt> in it - or rest2web
will ignore it. <img src="images/smilies/smile.gif" alt="Smile" /> </p>
<p><em>Every</em> rest2web page <em>must</em> start with a <a class="reference external" href="restindex.html">restindex</a>. This is a set of options
that tells rest2web how to build the page.</p>
<p>The index page is important. Some of the options you set in the <tt class="docutils literal"><span class="pre">restindex</span></tt>
of your index page apply to the whole directory.</p>
<p>The index page also has some extra information available to it (about the other
pages in the directory). This allows you to have in your index page, links to
each of the pages in that directory along with descriptions (including any
subdirectories).</p>
</div>
<div class="section" id="other-pages">
<h2><a class="toc-backref" href="#id25">Other Pages</a></h2>
<p>In order to be a <strong>rest2web</strong> source file, a file must be a text file
(<tt class="docutils literal"><span class="pre">.txt</span></tt>) and start with a <tt class="docutils literal"><span class="pre">restindex</span></tt>. There are over twenty different
options you can set in the restindex - but you will probably only need to use a
couple on most pages. Some of these options are only relevant to index pages
anyway.</p>
<p>A restindex looks like this :</p>
<pre class="literal-block">
restindex
format: html
page-title: This is the Page Title
crumb: Short Title
page-description:
This is a description of the page.
It can be more than one line long.
/description
/restindex
</pre>
<p>Immediately after the restindex comes the page contents. If this is in <a class="reference external" href="http://docutils.sourceforge.net">ReST</a>
format then <a class="reference external" href="http://docutils.sourceforge.net">docutils</a> will be used to turn it into html.</p>
<p>The page contents is then put into the template - and any special values are
converted. This allows for things like sidebars and navigation trails <a class="footnote-reference" href="#id12" id="id2">[2]</a> to
be added to your site.</p>
<p>After all the files in a directory have been processed, rest2web moves on and
processes any subdirectories.</p>
</div>
<div class="section" id="subdirectories">
<h2><a class="toc-backref" href="#id26">Subdirectories</a></h2>
<p>Subdirectories will also get rendered. Each subdirectory should have it's own
index page. This index page can be automatically linked to in the index page of
their parent directory.</p>
</div>
</div>
<div class="section" id="creating-an-example-site">
<h1><a class="toc-backref" href="#id27">Creating an Example Site</a></h1>
<p><acronym title="What Does Ok Stand For ?">Ok</acronym> - so let's see how this works in practise.
<img src="images/smilies/biggrin.gif" alt="Very Happy" /> </p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The simple site we create here can be seen in the <a class="reference external" href="tutorial_site/index.html">tutorial_site</a> <a class="footnote-reference" href="#id13" id="id3">[3]</a> folder
of the docs.</p>
</div>
<p>The first thing we'll do is create a config file.</p>
<div class="section" id="config-file">
<h2><a class="toc-backref" href="#id28">Config File</a></h2>
<p>If you were to create an example site from scratch you would need to create a
directory for it all to go in. In this tutorial our source directory will be
<tt class="docutils literal"><span class="pre">docs/tutorial_site</span></tt>, and the html will be put in <tt class="docutils literal"><span class="pre">docs_html/tutorial_site</span></tt>.</p>
<p>In our example we won't use any macros, so you can create a text file called
<tt class="docutils literal"><span class="pre">r2w.ini</span></tt> with the following values :</p>
<pre class="literal-block">
# these values are all left at the default
psyco = True
pause = False
log_file = 'log.txt'
DEBUG = False
compare_directory = ''
# these values we have edited for our site
start_directory = 'docs/tutorial_site'
target_directory = 'docs_html/tutorial_site'
macros = ''
</pre>
<p><small>This config file is actually called <em>'tutorial_site.ini'</em> in the distribution.</small></p></div>
<div class="section" id="html-template">
<h2><a class="toc-backref" href="#id29">HTML Template</a></h2>
<div class="sidebar">
<p class="first sidebar-title">Embedded Code</p>
<p>Special values are enclosed in either <tt class="docutils literal"><span class="pre"><%</span> <span class="pre">...</span> <span class="pre">%></span></tt> tags (for single
values) or <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt> tags for multiple statements.</p>
<p>Multiple statements are actually <a class="reference external" href="http://www.python.org">Python</a> code. You can embed chunks of code
into your pages and templates. This allows <em>unlimited expressiveness</em> in
how dynamic you make your pages and templates.</p>
<p class="last">If you wanted you could use your template to fetch information form the web
and include it in your pages. You can do anything that Python can do.</p>
</div>
<p>The HTML template has the basic framework of our website. We put special values
into the template - so that <strong>rest2web</strong> knows where to put things like the
page title, the page content, etc.</p>
<p>A website can use as many different templates as you want - for different parts
of the website, or even a different one for each page. <img src="images/smilies/surprised.gif" alt="Surprised" /> Most websites
will only need a single template though.</p>
<p>The full <a class="reference external" href="templating.html">doc page for templating</a> gives you a list of all the special values
we can use in our templates. (We can also use these in our page content). Last
count there were about twenty five of these values. Like the restindex, we can
create our basic site by only using a few of these.</p>
<p>We use these values in two different ways. For single values we surround the
values in <tt class="docutils literal"><span class="pre"><%</span> <span class="pre">...</span> <span class="pre">%></span></tt> tags. For chunks of code, we use <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt>.</p>
<p>We only need to use special values for things that are different in each page.</p>
<p>We save the template as <tt class="docutils literal"><span class="pre">template.txt</span></tt> and put it in the root directory of
our site. Because it doesn't start with a restindex, rest2web won't attempt to
process it as a page.</p>
<p>Here's our simple HTML template :</p>
<pre class="literal-block">
<!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" lang="en" xml:lang="en">
<head>
<title><% title %></title>
<meta http-equiv="Content-Type"
content="text/html; charset=<% final_encoding %>" />
<link rel="stylesheet"
href="<% path_to_root %>stylesheets/rest.css"
type="text/css" />
<link rel="stylesheet"
href="<% path_to_root %>stylesheets/test.css"
type="text/css" />
</head>
<body>
<div id="nav">
<ul>
<# print_crumbs(breadcrumbs) #>
</ul>
</div>
<div id="main>
<a name="startcontent" id="startcontent"></a>
<% body %>
<div id="end">
<p><a href="#startcontent">Return to Top</a><br />
<small>
Page last modified <strong><% modtime %></strong>.
</small>
</p>
</div>
</div>
</body>
</html>
</pre>
<p>It's actually <acronym title="eXtensible HyperText Markup Language">XHTML</acronym>, so it starts with the proper DOCTYPE <a class="footnote-reference" href="#id14" id="id4">[4]</a>. The rest
is a pretty simple document, with no real content.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p>We use two stylesheets in the template.</p>
<p>One is <tt class="docutils literal"><span class="pre">test.css</span></tt>, which contains the styles for our page <a class="footnote-reference" href="#id15" id="id5">[5]</a>.</p>
<p class="last">The other is <tt class="docutils literal"><span class="pre">rest.css</span></tt>, which has the styles for docutils generates HTML.</p>
</div>
<p>You can see the special values in the template. Let's look at the ones we have
used :</p>
<div class="section" id="special-values">
<h3><a class="toc-backref" href="#id30">Special Values</a></h3>
<ol class="arabic simple">
<li><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">title</span> <span class="pre">%></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">final_encoding</span> <span class="pre">%></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">path_to_root</span> <span class="pre">%></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><#</span> <span class="pre">print_crumbs(breadcrumbs)</span> <span class="pre">#></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">body</span> <span class="pre">%></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">modtime</span> <span class="pre">%></span></tt></li>
</ol>
<div class="section" id="title">
<h4><a class="toc-backref" href="#id31">title</a></h4>
<p><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">title</span> <span class="pre">%></span></tt> will be replaced with the title for each page. For index pages,
and pages in html format, you must specify the title in the restindex.</p>
<p>For pages in <tt class="docutils literal"><span class="pre">reST</span></tt> format, your top heading becomes the page title.</p>
</div>
<div class="section" id="final-encoding">
<h4><a class="toc-backref" href="#id32">final_encoding</a></h4>
<p><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">final_encoding</span> <span class="pre">%></span></tt> is the character encoding used for the page. This can
vary from page to page <em>or</em> you can set it for the whole site in your main
page.</p>
<p>In order to be valid html you <strong>must</strong> specify an encoding. If you don't know
about encodings then <strong>rest2web</strong> will attempt to work them all out for you -
and do the right thing. By default it will output the page using the same
encoding as the content.</p>
<p>To learn more about how rest2web handles encodings - read the <a class="reference external" href="reference/encodings.html">Text Encodings</a>
page.</p>
</div>
<div class="section" id="path-to-root">
<h4><a class="toc-backref" href="#id33">path_to_root</a></h4>
<p><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">path_to_root</span> <span class="pre">%></span></tt> is the path from the page being created to the root
directory (always ending in a <tt class="docutils literal"><span class="pre">/</span></tt> unless the page is in the root directory).</p>
<p>You might be used to specifying the location of stylesheets using the form
<tt class="docutils literal"><span class="pre">/stylesheets/styles.css</span></tt>. This gives the absolute location of the stylesheet -
but means that the file cannot be viewed correctly from the filesystem.</p>
<p>Using <em>path_to_root</em> for stylesheets and images (etc) puts the correct relative
path in - meaning that the site can be viewed from the filesystem.</p>
</div>
<div class="section" id="print-crumbs">
<h4><a class="toc-backref" href="#id34">print_crumbs</a></h4>
<p>You can see that <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">print_crumbs(breadcrumbs)</span> <span class="pre">#></span></tt> uses the second style of
tags - <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt>. That's because it's a function call not a value - and we
use it's output.</p>
<p><tt class="docutils literal"><span class="pre">print_crumbs</span></tt> is one of the built in <a class="reference external" href="functions.html">functions</a>. It prints the navigation
trails that are known by the weird name <em>breadcrumbs</em>. Tradition puts them at
the top of the page.</p>
<p>print_crumbs prints them as a list of items - so we put the function call
between unordered list tags <tt class="docutils literal"><span class="pre"><ul></span> <span class="pre">...</span> <span class="pre"></ul></span></tt>. There are some <acronym title="Cascading Style Sheets">css</acronym> rules
that cause them to be dispayed properly.</p>
</div>
<div class="section" id="body">
<h4><a class="toc-backref" href="#id35">body</a></h4>
<p><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">body</span> <span class="pre">%></span></tt> is the contents of the page. <img src="images/smilies/razz.gif" alt="Razz" /> </p>
</div>
<div class="section" id="modtime">
<h4><a class="toc-backref" href="#id36">modtime</a></h4>
<p><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">modtime</span> <span class="pre">%></span></tt> is the date (and time) that the source file was last modified.</p>
</div>
</div>
</div>
<div class="section" id="the-index-page">
<h2><a class="toc-backref" href="#id37">The Index Page</a></h2>
<p>When you run <strong>rest2web</strong> it scans the start directory, processing every text
file with a restindex. From each text file it creates a corresponding output
HTML file. By default, the filename of the output file will be the same as the
source file - except ending in <tt class="docutils literal"><span class="pre">.html</span></tt> instead of <tt class="docutils literal"><span class="pre">.txt</span></tt>. Having completed
all the files in a directory, rest2web then does any subdirectories.</p>
<div class="caution">
<p class="first admonition-title">Caution!</p>
<p class="last"><strong>rest2web</strong> will overwrite files in the target directory, creating all
necessary subdirectories.</p>
</div>
<p>So by default <tt class="docutils literal"><span class="pre">index.txt</span></tt> in the source directory becomes <tt class="docutils literal"><span class="pre">index.html</span></tt> in
the target directory. If you don't want your index page to be called
'index.html' then there are a couple of ways you can affect that. You can
either use the <tt class="docutils literal"><span class="pre">target</span></tt> keyword (in the restindex of course) to specify an
explicit target name for the target file, or you can use the <tt class="docutils literal"><span class="pre">index-file</span></tt>
keyword. 'index-file' tells rest2web that this file isn't the real index page -
but another one is instead. rest2web will then read that file and treat it as
the index page for the directory. Whichever you choose <em>every</em> directory must
have a file called <tt class="docutils literal"><span class="pre">index.txt</span></tt>, with a restindex, or rest2web will ignore
that directory.</p>
<p>Our file <tt class="docutils literal"><span class="pre">index.txt</span></tt> starts with a restindex. We're going to make it as
simple as possible.</p>
<p>Our index page is going to be a short introduction to the site, and have links
to all the other pages, with descriptions of them. For our main index page
we'll use HTML rather than ReST :</p>
<pre class="literal-block">
restindex
crumb: Home
format: html
page-title: rest2web Tutorial Website
/restindex
<h1 class="title">rest2web Tutorial Website</h1>
<h2 class="subtitle">An Example Index Page</h2>
<div class="displaybox">
<#
print_details(default_section)
#>
</div>
<p>This is the index for the <a href="../site.html">rest2web Tutorial
</a> website. It's not got much on it - other than this paragraph and
links to our other pages.</p>
</pre>
<p>The page is divided into two parts - the restindex, and the content.</p>
<div class="section" id="the-restindex">
<h3><a class="toc-backref" href="#id38">The restindex</a></h3>
<p>Every <strong>rest2web</strong> source page starts with a restindex. The restindex has
sensible defaults, so we only need to include values that we're changing. For
details of <em>all</em> the restindex options, read the <a class="reference external" href="restindex.html">restindex</a> page.</p>
<div class="sidebar">
<p class="first sidebar-title">Empty restindex</p>
<p>It's entirely possible that you might be happy with <em>all</em> the default
values in a restindex.</p>
<p>In this case you still need to start your page with an empty restindex :</p>
<pre class="last literal-block">
restindex
/restindex
</pre>
</div>
<p>We are using navigation trails in our template. That means each page should
have a <tt class="docutils literal"><span class="pre">crumb</span></tt>. Because this is the index page, we use the <em>traditional</em>
value <strong>Home</strong>.</p>
<p>Our page is html. The default format is html - this is <strong>rest2web</strong> after all
<img src="images/smilies/smile.gif" alt="Smile" /> - so we need include the <tt class="docutils literal"><span class="pre">format:</span> <span class="pre">html</span></tt> argument.</p>
<p>Because the page is html (and also because it is an index page <a class="footnote-reference" href="#id16" id="id6">[6]</a>) it needs a
<tt class="docutils literal"><span class="pre">page-title</span></tt>.</p>
<p>And that's all we need in our restindex. Wasn't that easy. <img src="images/smilies/razz.gif" alt="Razz" /> </p>
<p>We are relying on lots of default values - we don't define any sections for our
directory, we're ging to let rest2web handle all our encodings, and so on. The
<a class="reference external" href="restindex.html">restindex</a> page will tell you all the default values for the restindex options.</p>
</div>
<div class="section" id="the-content">
<h3><a class="toc-backref" href="#id39">The Content</a></h3>
<p>The content is nice and standard html <em>except</em>, we can see one of our special
values turning up again. This time it's a call to one of the
<a class="reference external" href="functions.html">standard functions</a> - <tt class="docutils literal"><span class="pre">print_details</span></tt>.</p>
<p><strong>print_details</strong> displays a nice list of links to all the pages in a
<em>section</em>. Your index page can be divided up into several <em>sections</em>. This
enables you to have one directory with pages on several different topics. Each
page then has a declaration in the restindex as to which section it is in.
(The <tt class="docutils literal"><span class="pre">section</span></tt> keyword in the restindex). You have to declare your list of
sections in the index page.</p>
<p>As you can see we <strong>haven't</strong> done that <img src="images/smilies/lol.gif" alt="Laughing" /> - so all the pages in our
directory will go into the default section.</p>
<p>You access a lot of data about <em>all</em> the pages in a directory using the
<tt class="docutils literal"><span class="pre">sections</span></tt> special value. You can read about that in the <a class="reference external" href="templating.html">templating</a> page
(along with all the other special values you can include in your pages).</p>
<p>You access information about the default section through <tt class="docutils literal"><span class="pre">sections[None]</span></tt>
<em>or</em> <tt class="docutils literal"><span class="pre">default_section</span></tt>. <tt class="docutils literal"><span class="pre">default_section</span></tt> is just an easier way to access
the same information.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p><tt class="docutils literal"><span class="pre">sections</span></tt> is a <a class="reference external" href="http://www.python.org">Python</a> object called a dictionary. You access members
through their keys. In the <tt class="docutils literal"><span class="pre">sections</span></tt> data structure each member is a
section. Each section is also a dictionary. Each section includes a list of
all the pages in that section.</p>
<div class="pysrc"><span class="pytext">section</span> <span class="pyoperator">=</span> <span class="pytext">sections</span><span class="pyoperator">[</span><span class="pystring">'section-name'</span><span class="pyoperator">]</span><br />
<span class="pytext">pages</span> <span class="pyoperator">=</span> <span class="pytext">section</span><span class="pyoperator">[</span><span class="pystring">'pages'</span><span class="pyoperator">]</span><span class="pytext"></span></div><p>Every directory has all the sections you define in the index page <em>and</em> the
default section. This has the key <tt class="docutils literal"><span class="pre">None</span></tt>. You can also access the default
section through the special value <tt class="docutils literal"><span class="pre">default_section</span></tt>.</p>
<p class="last">You can use dictionaries to build quite complex data structures. You can
learn more about dictionaries in the <a class="reference external" href="http://docs.python.org/tut/node7.html#SECTION007500000000000000000">Python Tutorial</a> or in the Python
docs about <a class="reference external" href="http://docs.python.org/lib/typesmapping.html">Mapping Types</a>.</p>
</div>
<p><strong>print_details</strong> takes an individual section to display all the pages in a
section. Any subdirectories in a directory can also be displayed as
'sub-sections'. Because all our pages will be in the default directory we
call print_details with the default section -
<tt class="docutils literal"><span class="pre"><#</span> <span class="pre">print_details(default_section)</span> <span class="pre">#></span></tt>.</p>
</div>
</div>
<div class="section" id="id7">
<h2><a class="toc-backref" href="#id40">Other Pages</a></h2>
<p>We've created our main page. The main page acts as an index to all the pages in
the directory.</p>
<p>So we need some content. Because this is <strong>rest2web</strong>, we'll create the page in
<acronym title="ReStructuredText">reST</acronym> format.</p>
<pre class="literal-block">
restindex
crumb: A Page
link-title: An Example Page
page-description:
This description is for the index page.
You can use **reST** markup if you want.
/description
/restindex
==============
A ReST Title
==============
--------------
The Subtitle
--------------
..
This is a comment. To use the 'raw-role', we have to define it
*first*.
.. role:: raw-html(raw)
:format: html
This page is written in ReStructured Text markup. That's
why it looks like *plain text*.
This page lives at :raw-html:`<em><% pagepath %></em>` [#]_. This tutorial
isn't a tutorial on ReStructuredText though. If you're looking for one, you
might be better off with the `docutils documentation`_.
.. [#] The file path is dynamically inserted by rest2web.
.. _docutils documentation: http://docutils.sourceforge.net
</pre>
<p>The restindex for this page is a bit different to the one for the index page.
ReST is the default markup, so we don't need to declare it explicitly in the
restindex. Additionally, docutils will automatically generate a page title for
us from the top level heading.</p>
<p>If we don't specify a crumb, the page title will be used <a class="footnote-reference" href="#id17" id="id8">[7]</a>. This is too
long, so we specify a short one.</p>
<p>We want this page to appear in the index page. It's entry will appear as a link
with a brief description. If we don't specify a link title, the page title will
be used. Often this will be ok - but here we've specified a different one <a class="footnote-reference" href="#id18" id="id9">[8]</a>.</p>
<p>So the text used for the link is the <tt class="docutils literal"><span class="pre">link-title</span></tt> value and the text used for
the description is the <tt class="docutils literal"><span class="pre">page-description</span></tt> value. This is a multi-line value
and can contain ReST markup.</p>
<div class="section" id="rest-content">
<h3><a class="toc-backref" href="#id41">reST Content</a></h3>
<div class="sidebar">
<p class="first sidebar-title">Embedded Code With reST</p>
<p>If you want to include multi-line chunks in rest documents, then you can
use the raw directive :</p>
<pre class="literal-block">
.. raw:: html
<#
big = '<big>%s</big>'
print big % 'Hello World'
#>
</pre>
<p class="last">Unlike the raw role, this doesn't need to be declared before you use it.</p>
</div>
<p>The content is straightforward reStructuredText. If you want an introduction
to ReST, <a class="reference external" href="http://docutils.sourceforge.net/user/rst/quickstart.html">A ReStructuredText Primer</a> is a good place to start.</p>
<p>Notice the use of the raw role : <tt class="docutils literal"><span class="pre">:raw-html:`<em><%</span> <span class="pre">pagepath</span> <span class="pre">%></em>`</span></tt>. This
allows us to insert <strong>rest2web</strong> special values into the page (without docutils
escaping the <em><</em> symbols). You can only use the raw role if you declare it
first.</p>
</div>
</div>
<div class="section" id="id10">
<h2><a class="toc-backref" href="#id42">Subdirectories</a></h2>
<p>Directories can have subdirectories. These appear in the index page as
'Subsections'.</p>
<p>The subdirectory must have an 'index.txt' file. The 'link-title' and
'page-description' specified here are what appear in the index page of the
directory above.</p>
<p>We'll create a subdirectory - imaginatively called 'subdirectory'. We'll create
the following file, and save it as 'index.txt' :</p>
<pre class="literal-block">
restindex
crumb: Subdirectory
target: subdirectory.html
page-description:
A subdirectory - with pages of it's own.
/description
/restindex
=========================
Subdirectory Index Page
=========================
--------------
The Subtitle
--------------
.. role:: raw-html(raw)
:format: html
.. raw:: html
<div class="indexblock">
<#
if not default_section['pages']:
print '<h2>No Pages Yet</h2>'
else:
print_details(default_section)
#>
</div>
.. class:: intro
This page lives at :raw-html:`<% pagepath %>`. The ``class``
directive applies a style to this paragraph.
</pre>
<p>I didn't want this page to be called <tt class="docutils literal"><span class="pre">index.html</span></tt>. I <em>could</em> have used the
<tt class="docutils literal"><span class="pre">index-file</span></tt> option to specify another file as being the index page. Instead
I stuck with keeping the source file as <em>index.txt</em>, but specifying an
alternative target filename. That's the <tt class="docutils literal"><span class="pre">target</span></tt> keyword.</p>
<p>This page is also in rest format. This means that we don't need to specify a
format in the restindex.</p>
<p>The content prints an index using <tt class="docutils literal"><span class="pre">print_details</span></tt> - but <em>only</em> if there are
any pages. It checks first (<tt class="docutils literal"><span class="pre">if</span> <span class="pre">not</span> <span class="pre">default_section['pages']:</span></tt>), and if there
aren't any it prints the <strong>No Pages Yet</strong> heading.</p>
<p>It also uses the <tt class="docutils literal"><span class="pre">class</span></tt> directive to apply a class to the paragraph - so
that it can be styled with CSS.</p>
</div>
</div>
<div class="section" id="more-advanced-topics">
<h1><a class="toc-backref" href="#id43">More Advanced Topics</a></h1>
<p>In this tutorial we haven't used any <a class="reference external" href="macros.html">macros</a>, or sidebars. Macros allow you to
easily insert smilies, python source coloring, and lots more into your pages.
The functions to create sidebars are described in the <a class="reference external" href="functions.html">standard functions</a>
page. There are many options in the restindex that we haven't explored here -
and also lots of special values that we haven't looked at.</p>
<p>Despite what it doesn't show, this tutorial does give you a good overview as to
how to create a website using <strong>rest2web</strong>. For further examples you can look
at the source files in the <tt class="docutils literal"><span class="pre">docs</span></tt> folder. These use most of the features of
<strong>rest2web</strong> - and you can see the results in the finished documentation.</p>
</div>
<hr class="docutils" />
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id44">Footnotes</a></h1>
<table class="docutils footnote" frame="void" id="id11" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>In the docs folder of the distribution.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>For some bizarre reason known as <em>breadcrumbs</em>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>The only difference is that the main index page has the <tt class="docutils literal"><span class="pre">include:</span> <span class="pre">No</span></tt>
option set - so that it doesn't go into the main index. <img src="images/smilies/razz.gif" alt="Razz" /> </td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>Purists might note that I <em>haven't</em> included the <acronym title="eXtensible Markup Language">xml</acronym> declaration.
This is because it puts <acronym title="Internet Exploder">IE</acronym> into quirks mode.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id15" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[5]</a></td><td>I've just re-used the main stylesheet for the rest2web docs. This is
easier for me - but it means there are a few extra values in there.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id6">[6]</a></td><td>Index pages need a <tt class="docutils literal"><span class="pre">page-title</span></tt> in the restindex. This is so that <strong>rest2web</strong>
doesn't have to build the page (for reST content) when examining the
index pages of it's subdirectories.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id17" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id8">[7]</a></td><td>For index pages the filename is used as the default crumb.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id18" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9">[8]</a></td><td>The link title can also be used by sidebars.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div id="end">
<p><a href="#startcontent">Return to Top</a><br />
<small>Part of the <a href="http://www.voidspace.org.uk/python/rest2web/">rest2web Docs</a></small><br />
<small>Page last modified <strong>Fri Aug 4 13:17:57 2006</strong>.</small>
</p>
</div>
</div></td>
</tr>
<tr>
<td valign="top" align="left" width="25%">
<div id="left-column">
<div id="sidie">
<ul>
<li class="left-navheader-first">
<a href="index.html" class="left-navheader">Index Page</a>
</li>
<li class="left-navheader">Pages</li>
<li><a href="introduction.html">Introduction</a></li>
<li><a href="quickstart.html">Quickstart</a></li>
<li><a href="config_file.html">Config File</a></li>
<li><a href="tutorial.html">Tutorial</a></li>
<li><a href="command_line.html">Command Line</a></li>
<li><a href="force_mode.html">Force Mode</a></li>
<li><a href="templating.html">Templates</a></li>
<li><a href="restindex.html">restindex</a></li>
<li><a href="functions.html">Functions</a></li>
<li><a href="macros.html">Macros</a></li>
<li><a href="special_files.html">Special Files</a></li>
<li class="left-navheader">Sub Sections</li>
<li><a href="reference/index.html">Reference</a></li>
<li><a href="test_site/index.html">Test Site</a></li>
<li><a href="translation/index.html">Translation</a></li>
<li><a href="gallery_test/index.html">Gallery</a></li>
</ul>
</div>
<p class="sidieimg">
<a href="http://www.python.org">
<img src="images/logos/new_python.gif" width="88"
height="103" border="0" alt="Powered by Python" />
</a>
</p>
<p class="sidieimg">
<a href="http://sourceforge.net/donate/index.php?group_id=138579">
<img src="http://images.sourceforge.net/images/project-support.jpg" width="100"
height="32" border="0" alt="Support This Project" />
</a>
</p>
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/rest2web/"><img
src="images/logos/rest2web140x62.gif" width="142" height="62"
alt="Site Built with rest2web" /></a><br />
</p>
</div>
</td>
</tr>
</table>
<hr />
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/rest2web/"><img src="images/logos/rest2web200x80.gif" width="200" height="80" alt="Site Built with rest2web" /></a>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=138579&type=5" width="210" height="62" alt="SourceForge.net Logo" /></a>
<a href="http://www.opensource.org"><img src="images/logos/osi-certified-120x100.gif" width="120" height="100" alt="Certified Open Source" border="1" /></a>
</p>
<p class="sidieimg">
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-203625-1";
urchinTracker();
</script>
</p>
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/index.shtml"><img
src="images/logos/pythonbanner.gif" width="468" height="60"
alt="Python on Voidspace" /></a>
</p>
<div id="footer">
Copyright © Voidspace<br />Design by <a href="http://www.fuchsiashockz.co.uk">Fuchsiashockz</a> | <a href="http://validator.w3.org/check?uri=referer" title="Validate code as W3C XHTML 1.1 Strict Compliant">W3C XHTML 1.1</a> | <a href="http://jigsaw.w3.org/css-validator/check?uri=referer" title="Validate Style Sheet as W3C CSS 2.0 Compliant">W3C CSS 2.0</a>
</div>
</div>
</body>
</html>
|