Rest2Web Quick start
This document shows how to create a very simple site with rest2web.
Make the following directory structure, with empty text files (directories, files).
Add the following to quickstart.ini:
psyco = False pause = False log_file = '/home/user/quickstart/qs_log.txt' DEBUG = False compare_directory = '' # these values we have edited for our site start_directory = '/home/user/quickstart/input' target_directory = '/home/user/quickstart/output' macros = ''
Change the /home/user/ prefix to a suitable location. For windows users, simply use the appropriate syntax (e.g. C:\data\quickstart\).
You may use any location for the start and target directories; they do not have to be siblings, nor do they have to reside underneath the same directory as the ini file.
Each source file corresponds to a content file, except under special circumstances (like telling rest2web not to process a directory, which we will cover later). Every source file needs a restindex block at the very top. The restindex can contain multiple options.
Add the following to quickstart/input/index.txt:
restindex crumb: quickstart root format: rest page-title: the quickstart root! encoding: utf-8 output-encoding: None /restindex
Add a restindex block to each index.txt file in the input/ tree, and also to any text files you want included in the build. The easiest way is copy the example, or modify what you placed in the input/index.txt root source file, and add it to each.
Remember to customize the crumb and page-title options!
Oh, and add some content to each page. That is the whole point, right?
The template controls how your site looks, what navigation features to include - basically anything outside of the content. We will use the same template as in the tutorial, and add the print_details(default_section) macro.
Add the following to quickstart/template.txt:
<!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="menu"> <# print_details(default_section) #> <p/> </div><!--#menu--> <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>
Run the following at the command line:
python /path/to/rest2web/r2w.py /path/to/quickstart/quickstart.ini -w
This builds your site, and display any warnings (-w). If you see any errors, read them from the bottom up (especially if they are Python errors like traceback) and fix them. If you cannot resolve an error, many helpful people on the rest2web mailing list are happy to help.
rest2web normally builds the entire site, ignoring any files not ending in ".txt" This can be a problem if you have pre-existing content, perhaps built by another process, that you simply want rest2web to link to.
Assume we already have subdir2 in the output/ directory, and rest2web should not overwrite that directory or the index.html file within it.
Create quickstart/input/subdir2/index.txt and add the following:
restindex # NOTE: the files listed here must reside in the OUTPUT directory; r2w will NOT copy them over crumb: subdir2 format: html page-title: subdir2's index encoding: utf-8 output-encoding: None target: index.html # "build: no" prevents this page from overwriting the existing subdir2/index.html page! build: no /restindex
Then rebuild the site.
As you may have guessed, the relevant option in the restindex block is build: no. This tells rest2web that there is a output/subdir2/index.html file, so do not overwrite it. The crumb and page-title options mean that rest2web will include those values in any site maps or sections. The section of your site that rest2web did not build will still be connected to the part that rest2web did build.
rest2web will not create subdir2/ or subdir2/index.html, so make sure you create it yourself.
Have files that you want to include but do not want them to get built? Or files that rest2web skips over, like .py text files or .png image files? Never fear! file: is here!
Result: quickstart/output/ now has somefile.abc!
Some reasons to use rest2web to handle files that it does not build: