= building blocks for creating Trac projects = [[TOC]] == Description == !TracLegos is software designed to template trac projects and assist with trac project creation. Its goal is to make project creation easy and flexible, allowing flexibility with regards to creation methodology as well as extensibility as a project factory for environments with advanced needs. !TracLegos is not [at least by design, yet] meant for project upgrading or maintainence, but only to setup a project with sensible defaults. !TracLegos can be invoked in a number of ways: * through a command-line interface (source:traclegosscript/anyrelease/traclegos/legos.py) * through a WSGI wrapper around trac (source:traclegosscript/anyrelease/traclegos/web.py) * via `paster create` * programmatically !TracLegos also makes it easy to turn an existing project into a [http://pythonpaste.org/script/developer.html#template PasteScript template]. == Bugs/Feature Requests == This is a new and somewhat experimental plugin so feedback and feature requests are greatly appreciated Existing bugs and feature requests for !TracLegosScript are [query:status!=closed&component=TracLegosScript&order=priority here]. If you have any issues, create a [/newticket?component=TracLegosScript&owner=k0s new ticket]. == Installation and Setup == Download the [download:traclegosscript zipped source], check out [/svn/traclegosscript using Subversion], or [source:traclegosscript browse the source] with Trac. Installation is done in the typical python manner. Once you have downloaded the source, run {{{python setup.py install}}} for installation into python's site packages or {{{python setup.py develop}}} to install with edittable source. === Installation of Example Template === TracLegosScript also comes with an existing template: source:traclegosscript/anyrelease/example/topp, which is an example of the kind of template used at [http://topp.openplans.org/ The Open Planning Project]. To install this template, run {{{python setup.py install}}} or {{{python setup.py develop}}} from this directory. This [http://pythonpaste.org/script/developer.html#templates PasteScript template] can be seen in the output of `paster create --list-templates`: {{{ (TracLegos)> paster create --list-templates Available templates: basic_package: A basic setuptools-enabled package paste_deploy: A web application deployed through paste.deploy topp_trac_project: The Open Planning Project Trac Template trac_project: templatize configuration for a trac project }}} === Turning an Existing {{{trac.ini}}} File into a Template === The last project shown in the templates listed by `paster create --list-templates`, [source:traclegosscript/anyrelease/traclegos/project.py trac_project], is a template designed to turn an existing [http://trac.edgewall.org/wiki/TracIni trac.ini] configuration file into a [source:traclegosscript/anyrelease/traclegos/project.py TracProject] template that can be used by TracLegosScript for project creation. To turn an existing configuration `trac.ini` into a [source:traclegosscript/anyrelease/traclegos/project.py TracProject] template, run: {{{ paster create -t trac_project yourproject }}} This will output a directory structure {{{ yourproject/ |-- setup.py |-- yourproject | |-- __init__.py | |-- project.py | `-- template | `-- conf | `-- trac.ini `-- yourproject.egg-info }}} To customize the template, edit `yourproject/yourproject/template/conf/trac.ini`. PasteScript template variables can be denoted and `pre` and `post` template writing setup can be done by customizing `yourproject/yourproject/project.py`. === Setup of [http://pythonpaste.org/webob/ WebOb] View for Project Creation === !TracLegos includes a [http://pythonpaste.org paste] webapp that serves existing projects (delegating to trac) and also allows creating new projects. In order to use this view, you must have at least one template installed, so first install the example template as described above. Once the {{{topp_trac_template}}} (or any other template) is installed, you should be all set to run the webapp by running {{{paster serve development.ini}}} from the top-level directory of your copy of the !TracLegos source (source:traclegosscript/anyrelease/development.ini). Point your browser at http://127.0.0.1:8080 and you should be all set with a bare-bones web-based trac project creator. == Site Configuration == !TracLegos is designed so that site-specific configuration does not need to (and really shouldn't) live in the templates but can live in its own {{{.ini}}} file. The advantages of this is that templates from XYZcorp can be shared with ABCcorp without modification but that a policy for trac project creation can be effectively enforced as well as having the convenience of domain-specific variables by using a site configuration {{{.ini}}} file (or files). Variables are currently supported in a site configuration file. See source:traclegosscript/anyrelease/example/site_example.ini for the format of this file. Using the command line, site configuration {{{.ini}}} files are specified with the `-c` option: {{{ create-trac-project -c example/site_example.ini ... }}} Configuration files may also be specified for the web front-end ''(not yet implemented! see #3761)''. To use this, add the following option to the {{{.ini}}} file specified for `paster serve`: {{{ traclegos.conf = /path/to/site_example.ini, /path/to/myorganization.ini }}} == Examples == === Example of through the web project creation === The index of the project additionally has a '''Create Project''' link: [[Image(index.png, border=1)]] Following this link will bring you to the initial screen of project creation where you select the project name and type of project (if more than one template is available): [[Image(create-project.png, border=1)]] Next, the project details screen will allow selection of the type of repository (and in the future, database type -- see #3745): [[Image(project-details.png, border=1)]] Finally, you must fill in any additional variables needed for the project: [[Image(project-variables.png, border=1)]] After completion, the project is created and you are redirected to it. === Example of command line usage === {{{ > create-trac-project Usage: create-trac-project [options] project <...> var1=1 var2=2 ... assemble a trac project from components Options: -h, --help show this help message and exit -c CONF, --conf=CONF site configuration files -d DIRECTORY, --directory=DIRECTORY trac projects directory -i INHERIT, --inherit=INHERIT .ini file to inherit from -r REQUIREMENTS, --requires=REQUIREMENTS requirements files for plugins -s REPOSITORY, --repository=REPOSITORY repository type to use -t TEMPLATES trac.ini templates to be applied in order --list-templates list available TracProject PasteScript templates --list-repositories list repositories available for setup by TracLegos > create-trac-project --list-templates Available projects: topp_trac_project: The Open Planning Project Trac Template > create-trac-project --list-repositories Available repositories: ExistingSVN: Use an existing repository NewSVN: Create a new SVN repository > create-trac-project -t topp-trac-project mynewproject # create a new project }}} === Example of turning an existing project into a pastescript template === {{{ > paster create -t trac_project foo Selected and implied templates: TracLegos#trac_project templatize configuration for a trac project Variables: egg: foo package: foo project: foo Enter file (file or project to templatize) ['']: /home/jhammel/20080519133401/projects/trachours/conf/trac.ini Enter description (One-line description of the package) ['']: a new trac template based on the trachours .ini file Creating template trac_project Creating directory ./foo Recursing into +package+ Creating ./foo/foo/ Copying __init__.py to ./foo/foo/__init__.py Copying project.py_tmpl to ./foo/foo/project.py Recursing into template Creating ./foo/foo/template/ Recursing into conf Creating ./foo/foo/template/conf/ Copying setup.py_tmpl to ./foo/setup.py Running /home/jhammel/TracLegos/bin/python setup.py egg_info > cd foo; python setup.py develop &> /dev/null > create-trac-project --list-templates Available projects: topp_trac_project: The Open Planning Project Trac Template foo: a new trac template based on the trachours .ini file }}} == Recent Changes == [[ChangeLog(traclegosscript, 3)]] == Author/Contributors == ''Originally developed at [http://topp.openplans.org The Open Planning Project]'' '''Author:''' [wiki:k0s] [[BR]] '''Contributors:'''