swift-hpa/README.md

swift-hpa

A command-line application for managing home performance assessment projects from user defined template repositories.

This tool is a wrapper around several other command line applications, the primary ones being:

1. ansible-playbook
2. ansible-vault
3. pandoc

Installation

You can install the application using homebrew.

brew tap michael/formula https://git.housh.dev/michael/homebrew-formula
brew install michael/formula/hpa

Installation on platforms other than macOS are currently being worked on, along with support for running in a docker container.

Ensuring dependencies are installed

This application requires some dependencies to be installed on your system, you can install the dependencies with the following command.

hpa utils install-dependencies

The dependencies installed are:

1. ansible
2. imagemagick
3. pandoc
4. texLive

It will also download an ansible-playbook that is used to generate output files, template repositories, and encrypt / decrypt variable files. The playbook get's installed to ~/.local/share/hpa/playbook.

NOTE: All commands accept a --help option which will display the arguments and options a command can use, along with example usage of the commands.

Configure the application

When you first download the application you can setup the configuration file for your use case.

hpa utils generate-config

This will create a configuration file in the default location: ~/.config/hpa/config.toml, which can be edited to suit your needs.

Getting Started

The first step to getting started is creating your template. This is used to create projects. The template defines the structure of a project and defines variables which are used to generate the final output files of a project.

You can generate the template using following command:

hpa utils generate-template --path ~/projects/my-template

Where the --path is where you would like the template to be on your local system.

It is recommended that after you get your template setup to your liking that you turn it into a git repository. Therefore your projects can be pinned to specific version of the template. This allows your template to expand over time.

Once your template is setup, make sure that your configuration file is setup to point to your customized template.

Creating a project

The first step after having your template defined is to create a project that uses it. The below command will create a template in the ~/consults/my-first-consult directory.

hpa create ~/consults/my-first-consult

The above assumes that your template is a git repository and that your configuration is setup properly. If you want to experiment with a local template that is on your system then you can you can use one of the following command options.

hpa create --template-dir ~/projects/my-template ~/consults/my-first-consult

Or if your configuration has directory set in the template section.

hpa create --use-local-template ~/consults/my-first-consult

Generating output files

Once you have created a project and edited the contents to your liking. You can then generate the final output file (typically a pdf) that can be sent to your customer.

hpa generate pdf

The above assumes that you are inside your project directory, if you would like to generate an output file from outside of your project directory you can specify the path to the project you would like to generate output for.

hpa generate pdf --project-directory ~/consults/my-first-consult

Currently the supported output file types are:

1. PDF
2. LaTeX
3. HTML

Build command

The command line tool goes through an intermediate step when generating output, which is called build. The build step generates the final output files using defined variables that are located in your project directory or in your template directory. It will decrypt any sensitive data stored in vault files as well.

These files get placed inside a directory in the project, default location is .build. The generate commands by default build the project for you, unless you specify the --no-build option.

You can explore the contents of the .build directory or if you'd like to separate the build and generate steps, you can build a project using the following command:

hpa build

The above assumes that you are inside your project directory, if you would like to generate an output file from outside of your project directory you can specify the path to the project you would like to generate output for.

hpa build --project-directory ~/consults/my-first-consult

Some General Usage Notes

There is often a lot of output to the console when running commands, which can be problematic if you want to pipe the output into other command line tools, so all options accept a -q | --quiet flag which will suppress logging output and allow piping into other commands.

Along the similar line, if you would like to increase the logging output then all commands accept -v | --verbose that will increase the logging output. This can be passed multiple times, so for the highest log output you can do -vvv.

Uninstalling

You can uninstall the application using:

brew uninstall hpa

Also remove the configuration and playbook directories.

rm -rf ~/.config/hpa
rm -rf ~/.local/share/hpa

LICENSE

This project is licensed under the MIT license.

See license