
Gazest site deployment manual
=============================


About
-----

Gazest is a community engine centered around a Wiki.  This document
describes how to setup and administer a Gazest site.

Gazest has two types of target users: systems administrators running a
Gazest powered site and visitors of such a site.  To prevent
confusion, this document use "user" or "visitor" for a person visiting
a Gazest powered site and "site admin" or "webmaster" for someone
deploying a Gazest site.


Install
-------

See `README.txt`.


Configuration
-------------

Most of the configuration is done through you `.ini` file.  Most
values should be self explanatory but the most obscure are described
here.

- `staging`: If `true`, robots and spiders are not allowed to the
  site.  Use this in the final stage of deployment but before you go
  live.

- `wiki_index`: Name of the page returned when accessing the wiki
  without a page name.  Most sites will never change that but there is
  a similar setting in MediaWiki so I suppose there is a use for that.

- `wiki_indexing_delay`: Time to way after a new page revision is
  committed before a spider can index it.  The time spec is the same
  format at GNU `sleep`.  This is good against spammers since you can
  weed out their links before the pages are indexed.

Customizing
-----------

Your Gazest site will hopefully have some branding of his own.  The
default `.ini` includes the lines

  extra_templates = %(here)s/extra_templates
  extra_statics = %(here)s/extra_statics

which refers to directories relative to your `.ini` file where you can
put files that will override the files included in the Gazest
distribution.

The first step in customizing the look of your site will be to add a
90 pixel hight image as `extra_static/img/top-banner.jpg`.  You can
change much of the style by CSS.  Just save your custom styles in
`extra_static/css/site.css`.  Have a look at the files packaged in
`gazest/public` to see what kind of style you need to produce.

It might happen that need more than CSS.  In that case you'll have to
override the Mako templates.  You should consult the
http://www.makotemplates.org/docs/[Mako manual] before you engage in
this adventure.  Now, have a look at the files packaged in
`gazest/templates`.  Most of the pages inherit from `base.mako` so it
will probably be your primary target for customization.  You can
override the template called `gazest/templates/foo.mako` by just
creating a file called `extra_templates/foo.mako`.  This include
templates rendered directly as a page, inherited templates, and
templates included in another template through `<% include ...%>`.



Wiki Macros
-----------

You can add "macros" to the wiki markup.  Tags like `{{foo.bar qux}}`
will look for a function `bar` in module `foo` and call it with a
`Page` object and the string `"qux"`.  You only have to register in
which modules the wiki can look for function with the
`gazest.wiki_macros` Setuptools
http://peak.telecommunity.com/DevCenter/setuptools#entry-points[entry
point].  

The lookup will not cross modules so in your macro module you can do

  import math
  from os import path

but not 

  from math import *


You can prevent a function from becoming a macro by naming it with a
leading underscore ("_").  Look at the `gazest_extra_macros` package
distribution for examples.

NOTE: You can use the `Page` object to produce "out of page" side
effects and other advanced rendering but this part of the API is not
stable yet.



Wiki Syntax
-----------

The syntax is handled in two parts: the wiki stuff and the
presentation stuff.  The wiki stuff is

  [[some page]]
  {{somemacro arg1 arg2}}

all the rest is left to the presentation renderer to expand.  The
default renderer is Markdown but the user can enable another one with
a macro.  See the `gazest_extra_macros` package for alternative
renderer.  As an example, to enable restructured text, one would add
this macro to his page:

  {{rst.enable}}

The choice of renderer is global to the page.  If more than one
renderer enabling macro is supplied, the last renderer is used.

You can change the rendered preferences from your `.ini`.  To change
the default renderer, put the enabling macro in the `wiki_header`; to
force the same renderer on all pages, put the enabling macro in
`wiki_footer`.
