= [TracLegosScript TracLegos] Configuration =

'''Note''': not all of the functionality presented herein has been implemented. This documentation primarily serves as a spec for how [TracLegosScript TracLegos] should work.

[TracLegosScript TracLegos] is designed to support several ways of creating trac projects: from the command line (`create-trac-project`), via a [http://pythonpaste.org paster] [source:traclegosscript/anyrelease/traclegos/web.py web interface], and via API calls to [source:traclegosscript/anyrelease/traclegos/legos.py#L100 TracLegos.create_project] and support functions such as [source:traclegosscript/anyrelease/traclegos/legos#L253].

In all three cases, you can have a site configuration file. The site configuration file contains [TracLegosTemplates template] variables appropriate to the particular site as well as driver configuration defining the project directory, database type, a default set of templates, and other configuration needed to define trac project creation. A site configuration `.ini` file may be used to enable a trac project creation policy, whether by convention (using `create-trac-project` from the command line) or by enforcement (using the web front end). The site configuration is tailored to the needs of a particular site or organization and so is not useful to share. Contrast this to [TracLegosTemplates trac project templates] which are generally meant to be generic and therefore sharable. 

== Site Configuration Example ==

An example site configuration is at source:traclegosscript/anyrelease/example/topp/site.ini :

[[Include(source:traclegosscript/anyrelease/example/topp/site.ini, text/plain)]]

There are two sections:

 * `[site-configuration]` contains defaults for arguments to [source:traclegosscript/anyrelease/traclegos/legos.py#L100 TracLegos.create_project] and the [source:traclegosscript/anyrelease/traclegos/legos.py#L32 TracLegos constructor]. These have the same name as specified on the command line and also the method arguments. ''This section also contains the database types and project types '''TO BE IMPLEMENTED?''' ''

 * `[variables]` contains default values for variables. For instance, if your company has a standard footer, and you are using which is set by `$footer` in templates, you could set `footer = Visit <a href="http://example.com">Our Company</a>"` to have a sane default.

== Use of [TracLegosScript TracLegos] Site Configuration ==

[[Image(source:traclegosscript/anyrelease/image/traclegos-conf.png)]]

This diagram illustrates the use of [TracLegosScript TracLegos] site configuration via three major methods of invocation:

 * via `create-trac-project -c`
 * via the web interface invoked by `paster serve`
 * via API calls to `TracLegos.create_project`

Running `create-trac-projct -c site-configuration.ini` will read the variables and defaults from the `site-configuration.ini` file. Additional parameters and variables passed via the command line will override those in `site-configuration.ini`. Additional templates passed in will be applied in order and overwrite configuration from previous templates.

Running `paster serve paster.ini` reads configuration from the `paster.ini` file. If `traclegos.conf` is set in section `[app:traclegos]` of the `paster.ini` file, site configuration will be read from that file (or comma separated list of files). Other configuration in the `[app:traclegos]` section of the `paster.ini` file will override those in the `[site-configuration]` file(s) specified by `traclegos.conf`. [TracLegosTemplates Template] variables may be specified in the `[DEFAULTS]` section of the `paster.ini` file which will override those given in the `[variables]` section of the `traclegos.conf` files.