this repo has no description
1`Odoc`'s generators (html, latex, and manpages) are tested by the building on dune's [include](https://dune.readthedocs.io/en/latest/dune-files.html#include) stanza idea to generate a dune file.
2
3### Directory layout
4```
5generators/
6 cases/
7 <case_name>.ml
8 gen_rules/
9 gen_rules.ml
10 dune
11 html/
12 <Case_name>-index.html
13 <Case_name>-X-index.html (** X is a module *)
14 <case_name>.targets (** contains html targets *)
15 ...
16 latex/
17 ...
18 man/
19 ...
20 dune
21 link.dune.inc
22 gen_rules_lib.ml
23 README.md
24 ...
25```
26
27`link.dune.inc` is checked out in the repository and is updated by a test rule.
28
29`generators/dune` contains the instruction of loading `link.dune.inc` and defines the rule to
30update it.
31
32`gen_rules.ml` is the program to generate `link.dune.inc`.
33
34Dependencies of `link.dune.inc` (information used by `gen_rules.exe` to compute it):
35- The list of test cases (this is obtained by scaning the `cases` directory)
36- A `.targets` file for each test case, which path is derived from the case's
37 name. If this file doesn't exist, we don't fail and assumes an empty list of
38 targets.
39
40**Note** :
41- when a test added has some new syntax, specifying a minimum bound on the ocaml version is required, and a maximum bound when a bug is fixed. These have to be specified as part of the [constraints](https://github.com/ocaml/odoc/blob/65074eeee3fe8478c4df5099cf83a95326484105/test/generators/gen_rules/gen_rules.ml#L75-L86).
42
43- If a test case is removed, or modified, for example when a module is removed from the test file, the results are expected to reduce but, the artefacts like `.target` file for the corresponding test case and the `html` file (for example) corresponding to the module removed aren't automatically removed from the file system. This thus requires one to manually remove the outdated `html` file.
44
45### To run the tests;
46- `dune runtest` -> This generates dune rules to compile, link, generate output targets <`html, latex, manpage`> targets, and the corresponding `.targets` files
47- `dune promote` -> promotes the generate rules.
48- Second `dune runtest` -> creates the `.target` file corresponding to a certain test case.
49- dune promote -> writes to the file system the `.target` file corresponding to a test cases
50- Third `dune runtest` -> create the output files ready to be written to file system, for example the html files
51- `dune promote` -> writes the output files to the file system.
52
53**Note** : you may need to run `dune clean && dune build` where expected files are not produced.