spruce

= Spruce - A tool for building CVs
:toc:
:toclevels: 1
:toc-title: Contents

== Overview

Spruce is a tool that generates a PDF document from a CV written in JSON.
The PDF generation is completed in two steps:

1. The application parses the JSON document and generates a TEX file using the TEX template files located in the https://codeflow.dananglin.me.uk/apollo/spruce/src/branch/main/internal/cmd/templates/tex[templates] directory.
2. The application then uses ConTeXt to generate the final PDF document from the generated TEX file.

== Requirements

Below is a list of required tools for installing and using spruce.

=== Go

A minimum version of Go 1.21.0 is required for installing spruce.
Please go https://go.dev/dl/[here] to download the latest version.

=== ConTeXt

ConTeXt is required for generating the PDF documentation.
You can go to the https://wiki.contextgarden.net/Installation[installation page] to find out how
to install ConTeXt for your Operating System.

=== The Carlito font (ttf-carlito)

Carlito is a free, metric compatible alternative to the Calibri font from Microsoft and is used when generating the PDF documentation.

For Debian/Ubuntu distributions you can use `apt` to install the font.
[source,console]
----
apt install font-crosextra-carlito
----

For Arch Linux you can use `pacman`.
[source,console]
----
pacman -S ttf-carlito
----

Alternatively you can download the font from https://fontlibrary.org/en/font/carlito[Font Library].

Once Carlito is installed you'll need to update ConTeXt so it can find the font when generating the PDF:
[source,console]
----
OSFONTDIR=/usr/share/fonts
mtxrun --script fonts --reload
----

=== Mage (Optional)

The project includes a https://codeflow.dananglin.me.uk/apollo/spruce/src/branch/main/magefiles/mage.go[magefile] for automating the build and installation of the spruce binary.
With Mage the build information is built into the binary when it is compiled.
You can visit the https://magefile.org[website] for instructions on how to install Mage.

=== Docker (Optional)

You can use Docker to build and use a docker image built with spruce and ConText installed.
This could be useful for those who are comfortable using Docker and don't want to install the above dependencies
directly onto their machines.

== Installation

=== With Mage

You can install spruce with Mage using the following commands:
[source,console]
----
git clone https://codeflow.dananglin.me.uk/apollo/spruce.git
cd spruce
mage install
----

The default install prefix is set to `/usr/local` so spruce will be installed to `/usr/local/bin/spruce`.
If you don't have sudo privileges or you want to change the install prefix you can set the `SPRUCE_INSTALL_PREFIX` environment variable before installing.
[source,console]
----
SPRUCE_INSTALL_PREFIX=~/.local mage install
----

=== With Go

If your `GOBIN` directory is included in your `PATH` then you can install spruce with Go.

[source,console]
----
git clone https://codeflow.dananglin.me.uk/apollo/spruce.git
cd spruce
go install ./cmd/spruce
----

=== Building the Docker image

You can build a docker image using the Dockerfile included in this project.
The build will build and install the spruce binary as well as install all the required dependencies in the final image.
You can build the docker image with the following command:
[source,console]
----
docker build -t spruce .
----

=== Verifying the installation

Run `spruce` to verify your installation. You should see the usage printed onto your screen.

[source,console]
----
$ spruce
SUMMARY:
  spruce - A command-line tool for building CVs

VERSION:
  v0.3.0

USAGE:
  spruce [flags]
  spruce [command]

COMMANDS:
  create        creates a new CV JSON file
  generate      generates a PDF file from an existing CV JSON file
  version       print the application's version and build information

FLAGS:
  -help, --help
        print the help message

Use "spruce [command] --help" for more information about a command.
----

If you've build the docker image you can get the same help message with the following command:

[source,console]
----
docker run --rm -it spruce
----

If you have installed spruce with Mage, you can get the build information to confirm that you have installed the correct version.
[source,console]
----
$ spruce version --full
Spruce
  Version: v0.1.0-14-ge503dbf
  Git commit: e503dbf
  Go version: go1.21.0
  Build date: 2023-08-12T13:00:51Z
----

If you've built the docker image you can verify it with the following command:
[source,console]
----
docker run --rm spruce version --full
----

== Generating the example PDF Document

Once you've installed spruce you can generate a PDF file from the example CV by running the following command:

[source,console]
----
spruce generate --input example/cv.json
----

This will create a file called `cv.pdf` which you can view with your favourite PDF viewer.

If you're using the docker image you can generate the PDF file using the following command:
[source,console]
----
docker run --rm -v ./example:/workspace spruce generate --input cv.json --output cv.pdf
----

The PDF file will be created in the `example` folder.

== Creating your own CV

To create your own CV run `spruce create`.
You can use additional flags to populate the CV with basic details such as your first name, last name and current job title.
Run `spruce create --help` to see all available flags.
After executing this command you'll find a file called **cv.json** which will contain the skeleton of your CV JSON document.

[source,console]
----
$ spruce create
│time=2023-08-18T13:21:10.120+01:00 level=INFO msg="CV successfully created" filename=cv.json
----

You can now start populating the fields with your favourite text editor.
Please refer to https://codeflow.dananglin.me.uk/apollo/spruce/src/branch/main/docs/schema.asciidoc[the schema reference] for more information on each field.
You can also check out the https://codeflow.dananglin.me.uk/apollo/spruce/src/branch/main/example/cv.json[example CV] as an additional guide.

Once you're happy with your CV you can run `spruce generate` to generate the PDF documentation.

[source,console]
----
$ spruce generate
time=2023-08-18T13:32:03.240+01:00 level=INFO msg="Creating the Tex file."
time=2023-08-18T13:32:03.252+01:00 level=INFO msg="Tex file successfully created." filename=/tmp/cv-builder-1016910977/cv.tex
time=2023-08-18T13:32:03.252+01:00 level=INFO msg="Creating the PDF document."
time=2023-08-18T13:32:06.416+01:00 level=INFO msg="PDF document successfully created." filename=/tmp/cv-builder-1016910977/cv.pdf
time=2023-08-18T13:32:06.416+01:00 level=INFO msg="File successfully copied." source=/tmp/cv-builder-1016910977/cv.pdf destination=cv.pdf
----

== Inspirations

- https://mszep.github.io/pandoc_resume/[The Markdown Resume:] This project uses ConTeXt and pandoc to convert Markdown based CVs into multiple formats including PDF, HTML and DOCX. This is where I discovered ConTeXt.
- https://github.com/melkir/resume/tree/master[melkir/resume:] This project generates CVs using Go and LaTeX.