README.md 3.45 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
(ql:quickload :quickref)
15
(quickref:refresh)
16
17
18
```

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

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

To run quickref from the image just do:

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

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

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

43
44
```
docker cp my-container:/home/quickbuilder/quickref .
45
46
47
48
49
50
```

## Advanced usage

### Multithreading

51
52
53
54
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.
55
56
57

### Custom `makeinfo` path

Antoine Martin's avatar
Antoine Martin committed
58
59
60
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:
61
62

```lisp
63
(quickref:refresh :makeinfo-path "/usr/local/bin/makeinfo")
64
65
66
67
68
69
70
71
72
73
```

### 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
74
(quickref:refresh :log-errors nil)
75
```
76
77
78
79
80
81
82
83
84
85
86
87

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

88
89
90
91
92
93
*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`).

94
95
96
97
98
### Building the images

To create the image with the build environment, run:

```
99
docker build -t quickref/buildenv -f Dockerfile-buildenv .
100
101
102
103
104
```

To create the final Quickref image, run:

```
105
docker build -t quickref .
106
```
107
108
109

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

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

The output should look like this: (with a different name/ID for you)
```
Antoine Martin's avatar
Antoine Martin committed
114
115
CONTAINER ID    IMAGE       COMMAND   CREATED         STATUS                     PORTS   NAMES
2b67991057f4    quickref    "bash"    6 seconds ago   Exited (0) 2 seconds ago           sleepy_morse
116
117
118
```

Then simply do:
119
120

```
121
docker cp sleepy_morse:/home/quickbuilder/quickref .
122
123
124
125
126
```

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.