README.md

# quickref

Quickref generates a website with reference manuals for every
[Quicklisp](https://www.quicklisp.org) library available.

The reference manuals are generated by
[Declt](https://github.com/didierverna/declt).

## Using `quickref`:

From your lisp REPL, just do:

```lisp
(ql:quickload :quickref)
(quickref:refresh)
```

This will trigger a complete cycle, which includes downloading and installing
the Quicklisp packages, generating the .texi files for all of them thanks to
Declt, and generating the final website structure by converting the .texi files
to HTML.

The generated files can by default be found in `$HOME/quickref/`.

## Docker image:

A Docker image is available, it ships with a complete build environment that
aims to reproduce the one used to create the Quicklisp releases. This means it
contains (almost) all the dependencies needed to build every library available
on Quicklisp.

To run quickref from the image just do:

```
docker pull quickref/quickref
docker run quickref/quickref
```

This will run `(quickref:refresh)` in the image.

You can then get the produced files with

```
docker cp my-container:/home/quickbuilder/quickref .
```

## Advanced usage

### Multithreading

Quickref supports multithreading; by calling `(quickref:refresh :parallel t)`.
Quickref will launch both the generation of `.texi` files and the generation of
`.html` files at the same time. This option is recommended if your machine has
multiple cores available.

### Custom `makeinfo` path

By default, Quickref will use the `makeinfo` found in your `PATH` to generate
the `.texi` files, but you can provide a custom one by calling Quickref with
the `:makeinfo-path` keyword argument:

```lisp
(quickref:refresh :makeinfo-path "/usr/local/bin/makeinfo")
```

### Logging

Errors are logged by default, logs can be found in
`quickref/logs/{declt,makeinfo}/`.

To disable logging, you can use the `log-errors` keyword argument:

```lisp
(quickref:refresh :log-errors nil)
```

## Docker images

You can build your own Quickref images by modifying the provided Dockerfiles:

`Dockerfile-buildenv` creates an image with all the dependencies needed to buid
the various Quicklisp libraries inside.

`Dockerfile` builds on top of the `buildenv` image and sets up a `quickbuilder`
user, pulls the latest versions of Quickref and Declt, and finally launches
Quickref.

*Note:*
The project is split into 2 separate images to allow rebuilding the final
quickref image with the `--no-cache` flag (to pull the latest version from the
git repo), without rebuilding the whole environment (including the hundreds of
dependencies installed from `apt`).

### Building the images

To create the image with the build environment, run:

```
docker build -t quickref/buildenv -f Dockerfile-buildenv .
```

To create the final Quickref image, run:

```
docker build -t quickref .
```

### Retrieving the website files from the image once Quickref finished running:

With `docker ps -a`, get the name/ID of your image.

The output should look like this: (with a different name/ID for you)
```
CONTAINER ID    IMAGE       COMMAND   CREATED         STATUS                     PORTS   NAMES
2b67991057f4    quickref    "bash"    6 seconds ago   Exited (0) 2 seconds ago           sleepy_morse
```

Then simply do:

```
docker cp sleepy_morse:/home/quickbuilder/quickref .
```

The entire `quickref/` folder will be copied, the `website` folder inside
contains all the necessary files, just copy them to the root of your webserver
of choice.