<%inherit file="/base.boot.mako"/> <%namespace file="/extensions.mako" import="*"/> ##name Welcome to Pyblue ##sortkey 1 ##tags home intro **PyBlue** is a simple way to easily generate static files used to present data analysis reports. * GitHub repository: [https://github.com/ialbert/pyblue][pyblue] * PyBlue Demo Site: [http://www.pyblue.org][pydemo] * The sources for the files in this demo: [https://github.com/ialbert/pyblue/tree/master/sites/demo][demo] * [A personal homepage][iua1] and an [organization page][bcc] created with **PyBlue** [iua1]: http://www.personal.psu.edu/iua1/index.html [bcc]: http://bcc.bx.psu.edu/ [pyblue]: https://github.com/ialbert/pyblue [pydemo]: http://www.pyblue.org [demo]: https://github.com/ialbert/pyblue/tree/master/sites/demo Getting Started --------------- *Zero configuration* - you may run **PyBlue** on any folder. * files that end with the extension `.html` will be passed through a [Mako template][mako] rendering. * files that start with dot `.`, or are Python `*.py` or Mako `*.mako` file will be ignored. * files that are larger than a certain size (default 5MB) see `utils.MAX_SIZE_MB` will also be ignored in the site generation step. If you have large files you must set up an efficient way to synchronize them across locations (like `rsync`) [mako]: http://www.makotemplates.org/ There are a few default templates in the templates folder to get you started. This demo site uses one of the default templates [base.boot.mako](https://github.com/ialbert/pyblue/blob/master/templates/base.boot.mako). You can place other Mako templates into the same folder that the site serves. **Note**: Rendering this demo site will generate a few warnings and even an error on the console. That is ok, it was done deliberately so to demonstrate how warnings and errors work. Extensions ---------- **PyBlue** offers a number of convenience extensions to be facilitate site generation. Importing `extensions.mako` file enables these functions. Linking ------- Linking to files can be achieved with the `link(pattern)` function. The pattern is a regular expression that should match the filename. * `link('index')` will produce ${link('index')} * If multiple files match the first will be picked: `link('b')` will produce ${link('b')} but you will also get warnings in the console. * If the pattern does not match you'll get an error message in the console and the link will also display the error: `link('joe')` will produce ${link('joe')} The url component of each link is relative. The text displayed for the link comes from the `name` context variable. When the `name` context is not explicitly set **PyBlue** will attempt to generate a readable name from the file name. See the ${link('context')} page on how to set the `name`. Table of Contents ------------------ You can iterate over all files in the project with `toc()` (Table of Contents). Users have control over the order in which files are listed and the name of the links that are displayed for each file. The `toc()` command can filter the files by regex pattern or tags . For example you can select files that match the word `base` with `toc(match='base')`: ${toc(match="base")} Or you can filter by tags, to show files tagged `home` use `toc(tag='home')` ${toc(tag="home")} The order of the entries listed with the `toc()` command is goverened by the `sortkey` context variable that defaults to `5`. See the ${link('context')} page on how to set the `sortkey`. Context ------- Any number of variables may be passed into each template. These will be available in the template body. See the ${link('context')} page on how to add tags to files. Galleries --------- You can easily generate galleries from images with the `gallery()` command. For details see ${link('gallery')} page. Advanced Usage -------------- You can embed the source of any file with the `source(fname)` function. For example `source("settings.py")` command will produce: ${source("settings.py")} As it happens this module named `settings.py` is special. If it is present it will be automatically imported under the attribute `p.settings` and can be accessed in every template. For this example one can access the `p.settings.data` to produce ${p.settings.data} This is a very handy way to pass common data across the site. Note that the `source` command can also take parameters such as `start` and `end`. When those are set only the region that between the matching regular expressions will be included. Capturing Output ---------------- The `execute(command)` function will insert the result of running a program into the page. If the source of a script stored in `demo.py` is ${source("demo.py")} then running it with `$execute('python demo.py')` will produce ${execute("python demo.py")} Automatic Markdown ------------------ Files with the extension `.md` will automatically be rendered as Markdown. This is the file included in the page: ${source("auto-markdown.md")} And this is the result of viewing the file directly: ${link('auto-markdown.md')} Testing Encoding ---------------- Accented characters: á é Full Table of Contents ---------------------- A listing of all files in this website: ${toc()}