Metadata-Version: 1.1
Name: miura
Version: 0.1.3
Summary: a Jenkins job management tool
Home-page: http://toumorokoshi.github.io/miura
Author: Yusuke Tsutsumi
Author-email: yusuke@yusuketsutsumi.com
License: UNKNOWN
Description: miura
        =====
        
        a Jenkins job management tool. Miura can create, update, and delete on
        mass for multiple jobs that vary slightly in configuration.
        
        Usage
        -----
        
        to create jobs with miura, the following is needed:
        
        * a job template, providing a template for a job
        * a directory, containing one or more files storing data with yaml
        * a python file, contaning
        
        Tutorial
        --------
        
        ### Getting Started
        
        Let's start with the most basic example. Create a directory scripts,
        and a file called example.py with the following:
        
            # scripts/example.py
            def run(options, data):
                yield {
                    'host': JENKINS_HOST_URL
                    'name': 'foo'
                    'template': 'base.xml'
                    'data': {}
                }
        
        And choose a job you want to copy off of, and download it to templates/base.xml:
        
            # with wget (Linux)
            mkdir -p templates && wget $JENKS_JOB_URL/config.xml -O templates/base.xml
            # with curl (OSX)
            mkdir -p templates && curl $JENKINS_JOB_URL/config.xml -o templates/base.xml
        
        And you're done! You can now create the foo job with:
        
            miura scripts/example.py
        
        Or the shorthand:
        
            miura example
        
        You can delete the jobs by passing in the script
        
            # delete jobs
            miura -d example
        
        See miura -h for a full explanation.
        
        ### Using templates
        
        Of course, this is not very helpful by itself. The real power of miura
        comes from not just generating one job, but generating multiple. Let's
        make a series of jobs that echo different messages to the console.
        
        Jenkins configurations can change over time, so this tutorial isn't
        going to include any examples of the xml that underlies jenkins
        jobs. It's a good idea to get familiar with config.xml files yourself:
        miura doesn't create these from scratch for you. Instead, miura
        specializies templates you write based off a job you want to
        replicate.
        
        * create a freestyle jenkins job "template" that echos 'foo' from the command line.
        * copy that job's config.xml file into templates/echo_template.xml.
            * you can access any job's config.xml file by hitting $JOB_URL/config.xml
        * replace the 'foo' in the config.xml with '{{ message }}', so it looks like the following:
        
            <!-- your markup may vary -->
            <hudson.tasks.Shell>
              <command>echo &apos;{{message}}&apos;</command>
            </hudson.tasks.Shell>
        
        miura uses the [jinja2](http://jinja.pocoo.org/docs/) templating
        language to specialize it's templates. In the example above, we're
        going to pass into the template a different message of each job, which
        will substitute {{message}} with a real value.
        
        Modify the script.py from before with the following:
        
            # scripts/example.py
            def run(options, data):
                for echo_message in ('bar', 'baz', 'bat'):
                    yield {
                        'host': JENKINS_HOST_URL
                        'name': 'echo-' + echo_message
                        'template': 'echo_template.xml'
                        'data': {
                            'message': echo_message
                        }
                    }
        
        And you're done! if you run the job now, you'll make three jobs: 'echo-bar', 'echo-baz', and 'echo-bat'.
        
        the run method in each script should yield a dictionary for each job
        to generate. our example yields through each message we want to create
        a job for, which miura in turn generates.
        
        ### Using data
        
        So now we've covered how to generate multiple jobs. But storing all
        our data with the script file is not very practical: we can't share
        data among our scripts, and we can't share data filtering code
        
        miura solves this problem by storing data in a separate format all
        together, and passing an aggregate dictionary of values into each method.
        
        Create a yaml file known as echo.yaml and add it to a directory data:
        
            # data/echo.yaml
            echo_messages:
              - 'bar'
              - 'baz'
              - 'bat'
        
        Now we have a separation of data and function. We can now remove the data from our script:
        
            # scripts/example.py
            def run(options, data):
                for echo_message in data.get('echo_messages'):
                    yield {
                        'host': JENKINS_HOST_URL
                        'name': 'echo-' + echo_message
                        'template': 'echo_template.xml'
                        'data': {
                            'message': echo_message
                        }
                    }
        
        And you're done!
        
        ### filtering data
        
        Now that we have our data in a format all our scripts can use, we can
        share filtering logic as well. If you want to filter your data, you
        can filter data with one or more filters:
        
            miura -f "echo_messages:ba[z|t]"
        
        ### Conclusion
        
        We've covered:
        
        * that miura runs commands through scripts (under scripts/)
        * that miura uses jinja to render templates (under templates/)
        * that miura can store data in a common location (under data/)
        
        Ultimately, our folder structure looks like:
        
        * /
            * data/
                * echo.yaml
            * scripts/
                * example.py
            * templates/
                * echo_template.xml
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Topic :: System :: Software Distribution
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
