![]() |
Rest2Web Quick startThis document shows how to create a very simple site with rest2web. Files and DirectoriesYou need:
Do thisMake the following directory structure, with empty text files (directories, files).
Things to note
ConfigurationDo thisAdd 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\). Explanation
Note 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. Source filesEach 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. Do thisAdd 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 restindex format
What it means
Do thisAdd 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? TemplatesThe 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. Do thisAdd 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> Build your siteRun 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. Ignoring and including filesrest2web 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. How to not overwrite a directoryAssume we already have subdir2 in the output/ directory, and rest2web should not overwrite that directory or the index.html file within it. Do thisCreate 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. Note rest2web will not create subdir2/ or subdir2/index.html, so make sure you create it yourself. How to include a fileHave 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! Do this
Result: quickstart/output/ now has somefile.abc! Some reasons to use rest2web to handle files that it does not build:
CongratulationsYou finished the rest2web quickstart! Next steps
Author and copyrightWritten by Andrew Ittner, © 2006. Licensed under the same license as rest2web. Return to Top |