Metadata-Version: 1.0
Name: topp.recipes.cfgtemplate
Version: 0.1.0dev-r19469
Summary: Provides template substitution for other recipe configurations in the same buildout.cfg file.
Home-page: http://topp.openplans.org/
Author: Rob Miller
Author-email: robm@openplans.org
License: GPLv3
Description: ========================
        topp.recipes.cfgtemplate
        ========================
        
        This is a zc.buildout recipe that provides support for template
        substitution within the buildout.cfg file.  When this recipe is loaded
        in a buildout.cfg file, it will search the buildout configuration for
        any instances of the the template syntax, i.e. any text enclosed by
        {{double-curly-braces}}.  If substitutions are found, the
        configuration will be altered directly in memory, and any subsequent
        recipes will be run with the substituted values.
        
        The template substitution values come from a separate config file,
        specified in the topp.recipes.cfgtemplate configuration, defaulting to
        "cfgsubs.cfg".  If the substitution file does not exist, or if it is
        missing any values required by the buildout.cfg file, then the user
        will be interactively prompted to enter the requested information, and
        the substitution file will be created or amended with the provided
        values.
        
        The idea is that you'll create a templatized buildout.cfg file and
        store it in a revision control system (RCS).  The templatized values
        would represent information that is not suitable for storage in the
        RCS, such as port numbers, passwords, database connection strings, or
        anything else that is either sensitive or likely to vary from
        deployment to deployment.  The first time this buildout.cfg file is
        used in a new location, the user will interactively provide these
        values, which would then be stored in the substitution file, which is
        left out of the RCS, or (if desired) is stored in a more secure
        repository elsewhere.
        
        Change history
        **************
        
        ${0.1.0 or "0.0.0"} (xxxx-xx-xx)
        ==================
        
        - Created recipe with ZopeSkel [${Rob Miller or ""}].
        
        Detailed Documentation
        **********************
        
        Supported options
        =================
        
        The recipe supports the following options:
        
        .. Note to recipe author!
        ----------------------
        For each option the recipe uses you shoud include a description
        about the purpose of the option, the format and semantics of the
        values it accepts, whether it is mandatory or optional and what the
        default value is if it is omitted.
        
        option1
        Description for ``option1``...
        
        option2
        Description for ``option2``...
        
        
        Example usage
        =============
        
        .. Note to recipe author!
        ----------------------
        zc.buildout provides a nice testing environment which makes it
        relatively easy to write doctests that both demonstrate the use of
        the recipe and test it.
        You can find examples of recipe doctests from the PyPI, e.g.
        
        http://pypi.python.org/pypi/zc.recipe.egg
        
        The PyPI page for zc.buildout contains documentation about the test
        environment.
        
        http://pypi.python.org/pypi/zc.buildout#testing-support
        
        Below is a skeleton doctest that you can start with when building
        your own tests.
        
        We'll start by creating a buildout that uses the recipe::
        
        >>> write('buildout.cfg',
        ... """
        ... [buildout]
        ... parts = test1
        ...
        ... [test1]
        ... recipe = topp.recipes.cfgtemplate
        ... option1 = %(foo)s
        ... option2 = %(bar)s
        ... """ % { 'foo' : 'value1', 'bar' : 'value2'})
        
        Running the buildout gives us::
        
        >>> print system(buildout)
        Upgraded:
        ...
        Installing test1.
        Unused options for test1: 'option2' 'option1'.
        
        
        
        Contributors
        ************
        
        ${Rob Miller or ""}, Author
        
        
        Download
        ********
        
Keywords: buildout
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
