Metadata-Version: 1.0
Name: pbp.recipe.trac
Version: 0.3.0
Summary: Expert Python Programming - ZC Buildout recipe that installs and configures a Trac server.
Home-page: http://pypi.python.org/pypi/pbp.recipe.trac
Author: Tarek Ziade
Author-email: tarek@ziade.org
License: GPL
Description: This recipe will help you setup a full-featured Trac instance via buildout.
        
        It allows you to automate the creation and management of multiples Trac
        instances. It provides sensible default to the ``trac.ini`` configuration file.
        It also takes care of instance upgrades, Wiki documentation updates and source
        code repository resynchronization.
        
        It currently supports Trac 0.11.x only, as for all future release of
        ``pbp.recipe.trac`` v0.3.x. Support of Trac 0.12.x is planned for
        ``pbp.recipe.trac`` v0.4.
        
        This package is part of the `Expert Python Programming` book written by Tarek
        Ziadé.
        
        .. contents::
        
        
        Detailed Documentation
        **********************
        
        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
        
        
        
        Contributors
        ************
        
        Tarek Ziade, Author [tarek]
        
        Kevin Deldycke, Contributor [kdeldycke]
        
        Change history
        **************
        
        0.3.0 (2010-10-08)
        ==================
        
        - Force upgrade of informations used during initialization: this is necessary
        to keep these parameters fresh if the Trac project structure already exists.
        [kdeldycke]
        
        - Get the latest Trac 0.11.x but exclude the 0.12.x branch.
        [kdeldycke]
        
        - Document all supported options.
        [kdeldycke]
        
        - Add new options: project-description and footer-message.
        [kdeldycke]
        
        - Reuse the description as alternative text to the logo.
        [kdeldycke]
        
        - Add support for all SMTP parameters.
        [kdeldycke]
        
        - Add support for trac.ini custom parameters.
        [kdeldycke]
        
        - Auto-install Pygments to benefit syntax highlighting.
        [kdeldycke]
        
        - Use pytz to get nice and friendly timezones.
        [kdeldycke]
        
        - Bring docutils to add reStructuredText (rst) support in Trac's wiki.
        [kdeldycke]
        
        - Add an option to let the user choose if default data added by Trac should be
        removed or not.
        [kdeldycke]
        
        - Auto-upgrade Trac instance against latest scheme. Add an option to let user
        force the upgrade.
        [kdeldycke]
        
        - Add an option to force upgrade of Wiki pages that are part of the
        self-documentation embedded in the Trac instance.
        [kdeldycke]
        
        - Set default value of the smtp-from-name parameter.
        [kdeldycke]
        
        - Add an option to force resynchronization of Trac against the source code
        repository.
        [kdeldycke]
        
        - Add an option to enable the time management plugin.
        [kdeldycke]
        
        - Replace buildbot-url parameter by a more generic additional-menu-items
        option.
        [kdeldycke]
        
        - Allow the creation of multiple custom milestones.
        [kdeldycke]
        
        - Add support for TracStats plugin.
        [kdeldycke]
        
        - Add support for the Subversion location plugin.
        [kdeldycke]
        
        - Add an option to set custom permissions.
        [kdeldycke]
        
        
        0.2.3 (2010-04-24)
        ==================
        
        - Fixed plugins svn paths.
        [tarek]
        
        
        0.1.0 (2008-06-16)
        ==================
        
        - Created recipe with ZopeSkel.
        [tarek]
        
        
        Download
        ********
        
Keywords: trac pbp buildout recipe
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Framework :: Trac
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
