checkpoint: move all docs to docs folder for flow site support
This commit is contained in:
parent
b2ce85b146
commit
1887436028
3 changed files with 221 additions and 1 deletions
|
@ -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.
|
||||
|
||||
|
|
214
docs/index.asciidoc
Normal file
214
docs/index.asciidoc
Normal file
|
@ -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.
|
|
@ -1,3 +1,6 @@
|
|||
---
|
||||
title: "Spruce - JSON schema reference"
|
||||
---
|
||||
= JSON schema reference
|
||||
|
||||
NOTE: This page was auto-generated with spruce-docgen.
|
||||
|
|
Loading…
Reference in a new issue