## -*- coding: utf-8 -*-
<%inherit file="/base.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')}

The default behavior for naming links is to get the `name` context variable of the page,
if that does not exists then the name of the file will be "humanized" with a heuristics.
Users can override this behavior and directly set the text that underlies the link with:

* `link('context', text='the context page')` will produce ${link('context', text='the context page')}

More examples:

* `link('context')` will produce ${link('context')}
* `link('gc_content')` will produce ${link('gc_content')}
* `link('gc_content', text="GC CONTENT")` will produce ${link('gc_content', text="GC CONTENT")}

* 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`.

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.

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`.

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 `include(fname)` function. For example  `include("settings.py")` command
will produce:

${include("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 `include` 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

${include("demo.py")}

then running it with `$execute('python demo.py')` will produce

${execute("python demo.py")}

Automatic Markdown/reST
-----------------------

It is possible to make files with the extension `.md` or 'rst' to
be rendered as html. To do so list the '.md' or `.rst` extension
in the `.include` file located in the root folder of your site.

This is the file included in the page:

${include("info/auto-markdown.md")}

And this is the result of viewing the file directly: ${link('auto-markdown.md')} and
${link('auto-rst.rst')}

Make note that for optimal results the webserver will also need to be set up
to return the `.md` and/or `.rst` extension with the HTML mime-type.

Testing Encoding
----------------

Accented characters: a, e, i --> á, é, í

To work with a specific character encoding make sure to encode both the file
and the HTML base template to indicate the encoding you wish to use.

This template starts with the following line:

<%text filter="h">
    ## -*- coding: utf-8 -*-
</%text>

The HTML base template also has the have `meta charset="UTF-8"` added to the header.

Full Table of Contents
----------------------

A listing of all files in this website:

${toc()}