Introduction
============

PopPage is a simple command-line utility originally intended as a static
website generator but has since grown into a
`cookiecutter <https://github.com/audreyr/cookiecutter>`__ clone. The
main features of PopPage are:

-  Uses `Jinja2 templates <http://jinja.pocoo.org/>`__ to generate
   output.

-  Uses YAML to store default key/values for template variables.

-  Output can be single files or directories.

-  Key/values applied to the templates variables can specified on the
   command line.

Status
======

Currently, this project is in the **development release** stage. While
this project is suitable for use, please note that there may be
incompatibilities in new releases.

Release notes are maintained in the project
`changelog <https://github.com/jeffrimko/PopPage/blob/master/CHANGELOG.adoc>`__.

Requirements
============

PopPage should run on any Python 2.7/3.x interpreter without additional
dependencies.

Usage
=====

PopPage can be run from the command line using ``poppage``. Type
``poppage --help`` for usage information. The following subcommands are
available:

-  ``check`` - Check the given INPATH template for variables.

-  ``make`` - Generates directories and files based on the given INPATH
   template.

-  ``run`` - Generates the OUTPATH, executes commands, then deletes
   OUTPATH.

Some Important Notes
--------------------

Before showing any examples, keep these notes in mind:

-  Template file/directory names can contain template variables (e.g.
   ``{{foo}}.txt``). The provided key/values will be used for the output
   file generation unless an explicit OUTPATH is provided.

-  The output will be passed to ``stdout`` if INPATH is a file (rather
   than a directory) and INPATH does not contain a template variable and
   no OUTPATH is specified.

CLI Key/Values
--------------

The following is a quick example of using PopPage from the CLI:

-  Template file (``template.jinja2``):

   ::

       Hello {{name}}!

-  PopPage command:

   ::

       poppage make --inpath template.jinja2 --string name world

-  Output to ``stdout``:

   ::

       Hello world!

YAML Key/Values
---------------

Additionally, default key/values can be stored in a YAML file:

-  Template file (``template.jinja2``):

   ::

       Hello {{name}}!

-  Defaults file (``defaults.yaml``):

   ::

       name: sun

-  PopPage command:

   ::

       poppage make --inpath template.jinja2 --defaults defaults.yaml

-  Output to ``stdout``:

   ::

       Hello sun!

Custom YAML Tags
----------------

The following custom YAML tags are provided:

-  ``!file`` - Reads value from a file as a string.

-  ``!yaml`` - Reads value from file as YAML.

-  ``!opt`` - Like ``!yaml`` but only for populating the ``opt`` key.

-  ``!cmd`` - Reads value from a CLI command output.

-  ``!ask`` - Prompts the user to input a value.

Check out this example:

-  Template file (``template.jinja2``):

   ::

       Hello {{first}} {{last}}!

-  Defaults file (``defaults.yaml``):

   ::

       first: !file myfile.txt
       last: !cmd python -c "print('Skywalker')"

-  Content of ``myfile.txt``:

   ::

       Anakin

-  PopPage command:

   ::

       poppage make --inpath template.jinja2 --defaults defaults.yaml

-  Output to ``stdout``:

   ::

       Hello Anakin Skywalker!

Option Defaults
---------------

Default utility options can be provided in the defaults file under the
``opt`` root key.

Check out these examples:

-  Basic option defaults:

   ::

       __opt__:
           inpath: template.jinja2
           outpath: myfile.txt

-  Another options example:

   ::

       __opt__:
           inpath: template.jinja2
           outpath: myfile.py
           execute: python myfile.py

-  The execute option can be a template:

   ::

       __opt__:
           inpath: template.jinja2
           execute: python {{outpath}}

-  Populate the options using a YAML file:

   ::

       __opt__: !opt myopts.yaml

Cookiecutter Compatiblity
-------------------------

PopPage should be compatible with many
`cookiecutter <https://github.com/audreyr/cookiecutter>`__ templates.
Using https://github.com/solarnz/cookiecutter-avr as an example, check
for the variables in the template:

::

    poppage check --inpath https://github.com/solarnz/cookiecutter-avr
    # Found variables:
    #   cookiecutter::full_name
    #   cookiecutter::repo_name
    #   cookiecutter::year

Create a file to store your default values, for example
``defaults.yaml``:

::

    cookiecutter:
        full_name: Henry Jones
        repo_name: LastCrusade
        year: 1989

Run PopPage to generate your files:

::

    poppage make --inpath https://github.com/solarnz/cookiecutter-avr --defaults defaults.yaml mydest
    # This will generate the entire repo to a new directory named mydest.

::

    # Or you can do:
    poppage make --inpath https://github.com/solarnz/cookiecutter-avr/tree/master/%7B%7Bcookiecutter.repo_name%7D%7D --defaults defaults.yaml
    # This will generate the {{cookiecutter.repo_name}} subdirectory to a new directory based on the given variables, in this case LastCrusade.

Similar
=======

The following projects are similar and may be worth checking out:

-  `cookiecutter <https://github.com/audreyr/cookiecutter>`__
