bookshelf-doc/README.md

47 lines
1.5 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 20:43:33 +00:00
1. `doc-gen4 single Init`
2. `doc-gen4 single Std`
3. `doc-gen4 single Lean`
4. `doc-gen4 single Mathlib`
Note that you can also just make a call to submodules so `Mathlib.Algebra`
will work standalone as well. Furthermore one can use the `--ink` flag
here to also generate LeanInk documentation in addition.
2022-07-21 17:07:35 +00:00
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
```