bookshelf-doc/README.md

50 lines
1.6 KiB
Markdown
Raw Normal View History

2021-11-11 01:41:28 +00:00
# doc-gen4
Document Generator for Lean 4
2021-12-12 12:27:38 +00:00
## Usage
You can call `doc-gen4` from the top of a Lake project like this:
```sh
2022-04-06 23:49:05 +00:00
$ /path/to/doc-gen4 Module
2021-12-12 12:27:38 +00:00
```
2022-04-06 23:49:05 +00:00
where `Module` is one or more of the top level modules you want to document.
2021-12-12 12:27:38 +00:00
The tool will then proceed to compile the project using lake (if that hasn't happened yet),
analyze it and put the result in `./build/doc`.
2022-06-20 20:51:22 +00:00
You can optionally provide the path to a `LeanInk` binary using the `--ink` flag which will make
the tool produce `Alectryon` style rendered output along the usual documentation.
2021-12-12 12:27:38 +00:00
You could e.g. host the files locally with the built-in Python webserver:
```sh
$ cd build/doc && python -m http.server
```
2022-07-21 16:32:09 +00:00
### Multi stage
You can also use `doc-gen4` in multiple separate stages to generate the whole documentation.
For example `mathlib4` consists out of 4 modules, the 3 Lean compiler ones and itself:
- `Init`
- `Std`
- `Lean`
- `Mathlib`
2022-07-21 17:07:35 +00:00
The first build stage is to run doc-gen for all modules separately:
2022-07-21 16:32:09 +00:00
1. `doc-gen4 single Init Mathlib`
2. `doc-gen4 single Std Mathlib`
3. `doc-gen4 single Lean Mathlib`
4. `doc-gen4 single Mathlib Mathlib`
2022-07-21 17:07:35 +00:00
We have to pass the `Mathlib` top level module on each invocation here so
it can generate the navbar on the left hand side properly, it will only
generate documentation for its first argument module.
Furthermore one can use the `--ink` flag here to also generate LeanInk
documentation in addition.
2022-07-21 19:12:15 +00:00
The second and last stage is the index one which zips up some
2022-07-21 17:07:35 +00:00
information relevant for the search:
2022-07-21 16:32:09 +00:00
```sh
2022-07-21 19:12:15 +00:00
$ doc-gen4 index Mathlib
2022-07-21 16:32:09 +00:00
```
Now `build/doc` should contain the same files with the same context as if one had run
```
$ doc-gen4 Mathlib
```