Dan Anglin
90638f5569
Add functionality to display the default help message when running spruce without any arguments or when the help flag is used. Customise the help message for the subcommands. Additional changes: - Refactor: move the Runner interface to the internal cmd package - Fix: Add a summary for each of the subcommands. - Refactor: Use string builder to replace string literals. - Perf: Use a switch statement to only create the subcommand that the user calls.
140 lines
4.2 KiB
Text
140 lines
4.2 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.
|
|
|
|
== 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
|
|
|
|
Run `spruce` to verify your installation. You should see the usage printed onto your screen.
|
|
|
|
[source,console]
|
|
----
|
|
$ spruce
|
|
A tool for building CVs
|
|
|
|
Usage:
|
|
spruce [flags]
|
|
spruce [command]
|
|
|
|
Available Commands:
|
|
create create a new CV JSON file
|
|
generate generate a PDF file from an existing CV JSON file
|
|
version print the application's build information
|
|
|
|
Flags:
|
|
-h, --help
|
|
print the help message for spruce
|
|
|
|
Use "spruce [command] --help" for more information about a command.
|
|
----
|
|
|
|
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.
|