From 1887436028864843f5bb113b5bd38c33b9ff5ab0 Mon Sep 17 00:00:00 2001 From: Dan Anglin Date: Mon, 5 Feb 2024 23:35:05 +0000 Subject: [PATCH] checkpoint: move all docs to docs folder for flow site support --- cmd/spruce-docgen/main.go | 5 +- docs/index.asciidoc | 214 ++++++++++++++++++++++++++++++++++++++ docs/schema.asciidoc | 3 + 3 files changed, 221 insertions(+), 1 deletion(-) create mode 100644 docs/index.asciidoc diff --git a/cmd/spruce-docgen/main.go b/cmd/spruce-docgen/main.go index 92304b0..687250e 100644 --- a/cmd/spruce-docgen/main.go +++ b/cmd/spruce-docgen/main.go @@ -11,7 +11,10 @@ import ( "unicode" ) -var schemaReferenceTemplate = `= JSON schema reference +var schemaReferenceTemplate = `--- +title: "Spruce - JSON schema reference" +--- += JSON schema reference NOTE: This page was auto-generated with spruce-docgen. diff --git a/docs/index.asciidoc b/docs/index.asciidoc new file mode 100644 index 0000000..0befe52 --- /dev/null +++ b/docs/index.asciidoc @@ -0,0 +1,214 @@ +--- +title: "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. diff --git a/docs/schema.asciidoc b/docs/schema.asciidoc index f3cff3d..11c4b0b 100644 --- a/docs/schema.asciidoc +++ b/docs/schema.asciidoc @@ -1,3 +1,6 @@ +--- +title: "Spruce - JSON schema reference" +--- = JSON schema reference NOTE: This page was auto-generated with spruce-docgen.