Metadata-Version: 1.1
Name: masonry
Version: 0.1.1
Summary: A command line tool for composable project templating.
Home-page: https://github.com/MrKriss/masonry
Author: Chris Musselle
Author-email: chris.j.musselle@gmail.com
License: MIT
Description: 
        Masonry
        =======
        
        |build status| |codecov|
        
            A command line tool for composable project templating.
        
        Masonry aims to reduce the need to write boiler plate code and setup
        files when starting or extending a project. It does so by allowing
        `cookiecutter <https://github.com/audreyr/cookiecutter>`__ templates to
        be combined in a series of layers to build up a projects file structure.
        
        Applying different combinations of these template building blocks then
        allow for a greater variety of project types to be more easily
        supported, compared to defining each template permutation separately.
        
        Masonry also includes a cli application ``mason`` that makes applying
        and managing these template layers straight forward.
        
        Installation
        ============
        
        ::
        
            pip install masonry
        
        Key Dependencies:
        -----------------
        
        -  ``cookiecutter`` >= 1.6
        
        Usage
        =====
        
        1. Create a series of template layers to use for a particular project
           layout (see below and in the project-templates directory for
           examples).
        
        2. Initialise a new project with its default starting template
        
           ::
        
               mason init project/template/path
        
        3. Add an extra templating layer to the project
        
           ::
        
               mason add template_name
        
        Creating and Using Template Layers for a Custom Project
        =======================================================
        
        The individual template layers are themselves cookiecutter templates. To
        combine several of these into a project to use with masonry:
        
        -  Each cookiecutter template should be in its own directory named after
           the templates purpose
        -  All these are then held in a parent directory, which is named after
           the project type all these layers relate to.
        -  Included in the project group directory is a metadata.json file that
           specifies the "default" template to use, as well as any dependencies
           between layers.
        
        For example, imagine a situation that wished to combine the following
        three layers into a project:
        
        1. One to create a base python package
        2. Another to define the unittest structure with pytest
        3. A third to add a build file for continuous integration.
        
        Placing these all in the same directory called "python-project" would
        give the following structure:
        
        ::
        
            path/to/python-project/
                        ├── ci-build
                        │   ├── {{cookiecutter.project_name}}
                        │   └── cookiecutter.json
                        │ 
                        ├── package
                        │   ├── {{cookiecutter.project_name}}
                        │   └── cookiecutter.json
                        │  
                        ├── pytest
                        │   ├── {{cookiecutter.project_name}}
                        │   └── cookiecutter.json
                        │
                        └── metadata.json
        
        The metadata.json file would then specify the *package* template as the
        default layer, with the *pytest* template layer depending on the
        *package* template, and the *ci-build* template layer depending on the
        *pytest* template. The structure of the resulting JSON file is shown
        below:
        
        .. code:: json
        
            {
                "default": "package", 
                "dependencies": {
                    "pytest": ["package"], 
                    "ci-build": ["pytest"]
                }
            }
        
        Now using ``mason`` we can create a new project following the *package*
        template with:
        
        .. code:: bash
        
                mason init path/to/python-project/
        
        And at a later time, when we want to start adding tests and a build
        process to the project, we could run:
        
        .. code:: bash
        
                mason add ci-build
        
        Note that even though we only specified "ci-build" above, ``mason`` is
        able to work out all needed template layer dependencies from the
        metadata.json and apply them in the right order. This means both the
        *pytest* and *ci-build* template layers will be applied in that order.
        
        Projects as a Collection of Components
        ======================================
        
        Splitting out the templates above may not seem to have gained you very
        much. After all, you could have just defined all these files for package
        + tests + CI in a single template structure. However, as you start to
        add different components to your projects under different scenarios,
        this modular approach becomes more beneficial.
        
        For example, say you wanted to support different CI services such as
        circle CI, travis, and GitLab Runners on different projects; and on some
        projects you have a Makefile, and on others something more cross
        platform compatible like an invoke tasks.py file.
        
        Accommodating all these options would either mean maintaining 6
        different templates with a lot of repetition, or one large one with a
        lot of control flow logic in the jinja template.
        
        Stomemason provides a middle ground of breaking up these components of
        the project into separate layers.
        
        It also has the major benefit of being able to apply any additional
        layers **after** the initial project was created. So if you didn't see
        the need to also create a conda package for your project till now? No
        problem, just apply the conda-package layer to the current project
        (assuming you have defined one of course!).
        
        Additional Features
        ===================
        
        -  Pre and post project creation hooks used by cookiecutter are
           supported.
        -  Cookiecutter variables are remembered and reused between template
           layers, meaning you only need to specify values for new variables.
        -  If project path is omitted, ``mason init`` allows you to
           interactively select one from a list of previously used projects.
        -  If the template name is omitted, ``mason add``, allows you to
           interactively select one from a list of templates that can still be
           added to the project.
        -  Colourful UI and easy multiple choice selection thanks to the
           `inquirer <https://github.com/magmax/python-inquirer>`__ library.
        
        Other Related Projects
        ======================
        
        -  `python boilerplate <https://www.python-boilerplate.com>`__ A web
           application for interactively filling out a template for a new
           project.
        
        -  `yeoman <http://yeoman.io/>`__ A project scaffolding tool for web
           development written in javascript.
        
        -  `mason <https://github.com/metacran/mason>`__ A project in R similar
           to cookiecutter but with a colourful UI, and one of the inspirations
           for this project.
        
        -  `usethis <https://github.com/r-lib/usethis>`__ A project in the R
           community looking at similar ideas around project template
           composability, and being able to add them as needed on a project.
        
        .. |build status| image:: http://img.shields.io/travis/MrKriss/masonry/master.svg?style=flat
           :target: https://travis-ci.org/MrKriss/masonry
        .. |codecov| image:: https://codecov.io/gh/MrKriss/masonry/branch/master/graph/badge.svg
           :target: https://codecov.io/gh/MrKriss/masonry
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
