Supported options
=================

The recipe supports the following options:

``project-name`` (required)

  Name of the Trac instance. This name will also be used as the default value
  for the ``smtp-from-name`` option. Default value: ``My project``.

``project-description``

  Description of the project. This description will also be used as the
  alternative text to the header logo.

``project-url``

  This URL will be used as the link on the header logo. Default value:
  ``http://example.com``.

``repos-type`` (required)

  Supported values: ``svn`` for Subversion, ``hg`` for Mercurial.

``repos-path`` (required)

  Location, on the local file system, of your code repository.

``repos-url``

  If set, this will enable and configure the `Subversion Location plugin
  <http://trac-hacks.org/wiki/SubversionLocationPlugin>`_. This only works for
  Subversion repositories.

``force-instance-upgrade``

  If set to ``True``, this will trigger the internal Trac upgrade process on
  the current instance, even if Trac don't think it's needed. Default value:
  ``False``.

``force-repos-resync``

  If set to ``True``, this will force the resynchronization of Trac against the
  source code repository. Default value: ``False``.

``wiki-doc-upgrade``

  If set to ``True``, this will upgrade the default wiki pages embedded in the
  current Trac instance. As said in Trac 0.11 documentation, this will not
  remove deprecated wiki pages that were previously part of a Trac release.
  Default value: ``False``.

``remove-examples``

  If set to ``False``, this will not remove the default milestones and
  components added by Trac when creating a brand new instance. Default value:
  ``True``.

``milestones``

  List of all custom milestones to create. You can add several custom
  parameters, one per line. Example::

    milestones = 0.1
                 0.2
                 1.0
                 Future
                 Undecided

``components``

  List of components for which we can attached Trac tickets to. The syntax must
  follow the ``Component name | Component owner`` scheme. Example::

    components = The application itself | kevin
                 Build tools            | cecile

``permissions``

  List of custom permissions to set. Both users and groups are supported.
  Example::

    permissions = cecile        | REPORT_ADMIN
                  kevin         | PERMISSION_ADMIN MILESTONE_ADMIN REPORT_ADMIN
                  anonymous     | STATS_VIEW
                  authenticated | REPORT_MODIFY MILESTONE_MODIFY

  A `list of permissions <http://trac.edgewall.org/wiki/0.11/TracPermissions>`_
  can be found on Trac's wiki.

``header-logo``

  Location of the logo that will replace the default Trac logo at the top of
  each page. The file will be copied by the recipe to the ``htdocs`` directory
  of your Trac instance.

``footer-message``

  The bottom right-aligned text displayed on each page displayed by Trac. HTML
  can be used here. Default value ``This Trac instance was generated by
  <a href="http://pypi.python.org/pypi/pbp.recipe.trac">pbp.recipe.trac</a>.``.

``smtp-always-bcc``

  Email address(es) to always send notifications to, addresses do not appear
  publicly (Bcc:).

``smtp-always-cc``

  Email address(es) to always send notifications to, addresses can be seen by
  all recipients (Cc:).

``smtp-default-domain``

  Default host/domain to append to address that do not specify one

``smtp-enabled``

  Enable SMTP (email) notification.

``smtp-from``

  Sender address to use in notification emails.

``smtp-from-name``

  Sender name to use in notification emails. Default value: ``project-name``
  option value.

``smtp-password``

  Password for SMTP server.

``smtp-port``

  SMTP server port to use for email notification.

``smtp-replyto``

  Reply-To address to use in notification emails.

``smtp-server``

  SMTP server hostname to use for email notifications.

``smtp-subject-prefix``

  Text to prepend to subject line of notification emails. If the setting is not
  defined, then the value of ``project-name`` is used as prefix. If no prefix
  is desired,then specifying an empty option will disable it.

``smtp-user``

  Username for SMTP server.

``additional-menu-items``

  This will use the `NavAdd plugin <http://trac-hacks.org/wiki/NavAddPlugin>`_
  to add new menu entries in Trac's top navigation toolbar. The syntax must
  respect the following scheme: ``Title | Url``. You can specify multiple menu
  entries as shown in the following example::

    additional-menu-items = Buildbot      | http://localhost:9080/
                            Demo instance | http://trac.edgewall.org/demo-0.13

``time-tracking-plugin``

  If set to ``enabled``, will activate the `Estimation and Time Tracking plugin
  <http://trac-hacks.org/wiki/TimingAndEstimationPlugin>`_. Default value:
  ``disabled``.

``stats-plugin``

  If set to ``enabled``, will activate the `TracStats plugin
  <http://trac-hacks.org/wiki/TracStatsPlugin>`_. Default value: ``disabled``.

``trac-ini-additional``

  In case a Trac parameter is not natively supported by this recipe, you can
  use this to add your own. The syntax must respect the following scheme:
  ``Section | Parameter | Value``. You can add several custom parameters, one
  per line. Example::

    trac-ini-additional = attachment   | max_size            | 52428800
                          notification | always_notify_owner | true
                          logging      | log_level           | DEBUG

  This option is applied just before writing the final ``trac.ini`` generated by
  this recipe. So thanks to ``trac-ini-additional``, you always have a way to
  fix your ``trac.ini`` even if this recipe breaks it.

  And to get more informations on all the ``trac.ini`` parameters, see:
  http://trac.edgewall.org/wiki/0.11/TracIni


Example usage
=============

We'll start by creating a buildout that uses the recipe::

    >>> write('buildout.cfg',
    ... """
    ... [buildout]
    ... parts = trac
    ... index = http://pypi.python.org/simple
    ...
    ... [trac]
    ... recipe = pbp.recipe.trac
    ... project-name = My project
    ... project-url = http://example.com
    ... repos-type = hg
    ... repos-path = sqlite:${buildout:directory}/var/svn
    ... header-logo = ${buildout:directory}/my_logo
    ... smtp-server = localhost
    ... smtp-port = 25
    ... smtp-from = tarek@ziade.org
    ... smtp-replyto = tarek@ziade.org
    ... """)

Let's run the buildout::

    >>> res = system(buildout)

This creates a trac instance::

    >>> ls(join(sample_buildout, 'parts', 'trac'))
    -  README
    -  VERSION
    d  attachments
    d  conf
    d  db
    d  htdocs
    d  log
    d  plugins
    d  templates

With a trac.ini file. Let's check its content::

    >>> f = join(sample_buildout, 'parts', 'trac', 'conf', 'trac.ini')
    >>> from ConfigParser import ConfigParser
    >>> parser = ConfigParser()
    >>> null = parser.read([f])
    >>> parser.get('trac', 'repository_type')
    'hg'
    >>> parser.get('trac', 'repository_dir')
    '/sample-buildout/var/svn'
    >>> parser.get('project', 'descr')
    'My example project'
    >>> parser.get('project', 'name')
    'My project'
    >>> parser.get('project', 'url')
    ''
    >>> parser.get('components', 'tracext.hg.*')
    'enabled'


Support
=======

- Documentation: http://pypi.python.org/pypi/pbp.recipe.trac

- Bug tracker: http://bitbucket.org/tarek/atomisator/issues

- Source: http://bitbucket.org/tarek/atomisator/src/tip/packages/pbp.recipe.trac/

- pbp.recipe.trac is a sub-project of atomistor: http://atomisator.ziade.org


