Dan Anglin
649f074d25
Changes: - ci: Add a workflow for Forgejo Actions - docs: Update README.asciidoc - tests: add a mage target for running tests
210 lines
6.9 KiB
Text
210 lines
6.9 KiB
Text
= 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.
|