Dan Anglin
82bdc231e3
- Convert README.md to README.asciidoc - Update the requirements section - Add installation section
117 lines
3.6 KiB
Text
117 lines
3.6 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 link:./internal/cmd/templates[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 link: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.
|
|
|
|
== 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 .
|
|
----
|
|
|
|
=== Verifying the installation
|
|
|
|
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
|
|
----
|
|
|
|
== Generating the example PDF Document
|
|
|
|
Once you've installed spruce you can generate a PDF 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 in your favourite PDF viewer.
|
|
|
|
== 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.
|