Michael Housh
daeeffa995
All checks were successful
CI / Run Tests (push) Successful in 2m25s
Reviewed-on: #3
180 lines
5.5 KiB
Markdown
180 lines
5.5 KiB
Markdown
# 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`
|
|
1. `ansible-vault`
|
|
1. `pandoc`
|
|
|
|
## Installation
|
|
|
|
You can install the application using homebrew.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
hpa utils install-dependencies
|
|
```
|
|
|
|
The dependencies installed are:
|
|
|
|
1. ansible
|
|
1. imagemagick
|
|
1. pandoc
|
|
1. 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
hpa create --template-dir ~/projects/my-template ~/consults/my-first-consult
|
|
```
|
|
|
|
Or if your configuration has `directory` set in the `template` section.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
hpa generate pdf --project-directory ~/consults/my-first-consult
|
|
```
|
|
|
|
Currently the supported output file types are:
|
|
|
|
1. PDF
|
|
1. LaTeX
|
|
1. 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
brew uninstall hpa
|
|
```
|
|
|
|
Also remove the configuration and playbook directories.
|
|
|
|
```bash
|
|
rm -rf ~/.config/hpa
|
|
rm -rf ~/.local/share/hpa
|
|
```
|
|
|
|
## LICENSE
|
|
|
|
This project is licensed under the `MIT` license.
|
|
|
|
[See license](https://git.housh.dev/michael/swift-hpa/LICENSE)
|