README.md 2.51 KB
Newer Older
Antoine Martin's avatar
Antoine Martin committed
1
2
# quickref

3
4
Quickref generates a website with reference manuals for every
[Quicklisp](https://www.quicklisp.org) library available.
Antoine Martin's avatar
Antoine Martin committed
5

6
7
8
9
10
The reference manuals are generated by
[Declt](https://github.com/didierverna/declt).

## Using `quickref`:

11
From your lisp REPL, just do:
Antoine Martin's avatar
Antoine Martin committed
12

Antoine Martin's avatar
Antoine Martin committed
13
```lisp
14
15
16
(ql:quickload :quickref)
(use-package :quickref)
(refresh)
17
18
19
```

This will trigger a complete cycle, which includes downloading and installing
20
21
22
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.
23
24
25
26
27
28

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
29
30
31
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.
32
33
34

To run quickref from the image just do:

Antoine Martin's avatar
Antoine Martin committed
35
```
36
37
38
39
40
docker pull quickref/quickref
docker run quickref/quickref
```

This will run `(quickref:refresh)` in the image.
Antoine Martin's avatar
Antoine Martin committed
41

42
You can then get the produced files with
Antoine Martin's avatar
Antoine Martin committed
43

44
45
```
docker cp my-container:/home/quickbuilder/quickref .
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
```

## Advanced usage

### Multithreading

Quickref supports multithreading; by calling `(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 `/usr/local/bin/makeinfo` to generate the `.texi`
files, but you can provide a custom one by calling Quickref with the
`:makeinfo-path` keyword argument:

```lisp
(refresh :makeinfo-path "/usr/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
(refresh :log-errors nil)
```
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

## 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.

### Building the images

To create the image with the build environment, run:

```
docker build -t my_image_name -f Dockerfile-buildenv .
```

To create the final Quickref image, run:

```
docker build -t my_image_name .
```