jon.recoil.org
this repo has no description
1# Contributing
2
3Welcome to the `odoc` project, and we're thrilled that you're considering contributing!
4
5This guide serves as a roadmap for your contribution journey. It lays out the necessary steps and guidelines to ensure a smooth contribution experience, from setting up your development environment to making a pull request.
6
7## Quick Start: HTML and CSS
8
9The CSS for `odoc` is located at [src/html_support_files/odoc.css](https://github.com/ocaml/odoc/blob/master/src/html_support_files/odoc.css). We're continually working to improve it and welcome your contributions. You can edit CSS using your browser's [developer tools](https://developer.mozilla.org/en-US/docs/Tools) or [Chrome DevTools](https://developer.chrome.com/docs/devtools/). Once you've made your changes, submit a pull request with those changes.
10
11Contributing to the HTML is slightly more complex. The main HTML generator is in [src/html/generator.ml](https://github.com/ocaml/odoc/blob/master/src/html/generator.ml). It operates on types defined in `Odoc_document.Types`, an intermediate representation used by all output renderers. The type describing an individual HTML page is `Odoc_document.Types.Page.t`.
12
13Here's a step-by-step guide to get you set up for HTML contribution:
14
151. **Install requirements:**
16 * Install a recent version of [HTML Tidy](http://www.html-tidy.org/) (used for HTML validity testing). Here's how:
17 - On MacOS (should be version 5.8 by the date of this writing): `brew install tidy-html5`
18 - On Debian / Ubuntu: `sudo apt-get install tidy`
19 * Install a recent version of [`jq`](https://github.com/stedolan/jq). Here's how:
20 - On MacOS: `brew install jq`
21 - On Debian / Ubuntu: `sudo apt-get install jq`
22
232. **Set up for development:**
24 Clone the `odoc` repository, navigate into the new directory, and install dependencies with these commands:
25 ```
26 git clone https://github.com/ocaml/odoc.git
27 cd odoc
28 opam install --with-test --deps-only ./odoc-parser.opam ./odoc.opam
29 ```
30
313. **Make and test changes:**
32 After making your changes, compile the code with `make` and then run the tests with `make test`. Any changes to the HTML are likely to cause tests to fail - see the Testing section below to understand how to update them.
33
344. **Test `odoc` against your project:**
35 Clean the build with `make clean`, then install `odoc` with `opam install odoc`. Because `odoc` is pinned, this will install your modified version. You can then run `odoc` in your project as you normally would: `dune build @doc`.
36
375. **Submit a pull request:**
38 If everything looks good, feel free to submit a pull request. We appreciate your contribution!
39
40## Testing
41
42`odoc` uses a variety of different test types. We are slowly converging on using Dune's [Cram tests](https://dune.readthedocs.io/en/stable/tests.html#cram-tests), though we still have many tests that aren't yet converted.
43
44### Cram Tests
45
46The tests extensively use these for the model layer and are found in [test/xref2](https://github.com/ocaml/odoc/blob/master/test/xref2). These consist of a directory called `something.t`, containing a file `run.t`. This file has shell-like syntax and usually runs `odoc` on some carefully crafted input files.
47
48For tests of the model layer, it's often useful to use the binary `odoc_print` which can dump `.odoc` and `.odocl` files as JSON. This output can then be piped through jq to verify that values are as expected.
49
50We try to make these test files describe the test and what's expected, which helps when the output isn’t what the test expected. This also means that the tests can serve as documentation of how things work. As an example, see the file [test/xref2/multi_file_module_type_of.t/run.t](https://github.com/ocaml/odoc/blob/master/test/xref2/multi_file_module_type_of.t/run.t)
51
52The tests work by executing the shell script snippets and then comparing the actual output with those in the `run.t` files. If these don't match, the difference is rendered as a diff.
53
54If the test is broken, run `dune promote` to replace the expected output with the current output.
55
56### Other Expect-Tests
57
58Many of `odoc`'s older tests are custom Expect-tests, similar to those run in the Cram test above, but that don't use Dune's promote workflow.
59
60When one of these Expect-tests fail, the output is saved, so the developer can choose to replace the now-incorrect expected string. For these custom Expect-tests, the results may look like the example given in the OCamldoc.
61
62We are slowly shifting these custom Expect-tests over to the Dune promote workflow.
63
64### Coverage Analysis
65
66The `odoc` repo is set up for coverage analysis. This is most useful if you're writing new tests and want to know what they’re actually touching.
67
68To use it:
69
70- Run `make coverage`. This will run the tests as normal, except at the end you’ll get a message like
71```
72 See _coverage/index.html
73```
74You can then open `_coverage/index.html` and see the coverage of the code you’d like your new test to reach.
75
76- Write new tests
77- Check coverage again
78
79### CI Tests
80
81`odoc` is tested by [OCaml-CI](https://ci.ocamllabs.io/) and by GitHub workflows. One of these also does a coverage build, so we have up-to-date coverage stats on [Coveralls](https://coveralls.io/github/ocaml/odoc).
82
83The tests cover esy and opam builds on Windows, macOS, and Linux. The Linux tests cover all supported versions of OCaml. We strive to retain compatibility back as far as we can (currently 4.02) which is important for supporting [ocaml.org/docs](https://ocaml.org/docs/).
84
85## API Reference
86
87### Loading
88
89The [`odoc.loader`](https://ocaml.github.io/odoc/odoc/odoc.loader/) library is responsible for converting from the OCaml [`Typedtree`](https://ocaml.github.io/odoc/ocaml-base-compiler/compiler-libs.common/Typedtree/index.html) representations to the [internal representation](https://ocaml.github.io/odoc/odoc/odoc.model/Odoc_model/Lang/index.html).
90
91### Model
92
93The [`odoc.model`](https://ocaml.github.io/odoc/odoc/odoc.model/) library contains definitions of the internal types used to represent OCaml interfaces.
94
95### Resolution and Expansion
96
97Resolution of Paths, Fragments and References, and Expansion of Modules and Module Types are handled by the [`odoc.xref2`](https://ocaml.github.io/odoc/odoc/odoc.xref2/) library.
98
99### Intermediate Representation and Renderers
100
101The generic documentation intermediate format is defined in the [`odoc.document`](https://ocaml.github.io/odoc/odoc/odoc.document/) library.
102
103The three current renderers are implemented within the following libraries: [`odoc.html`](https://ocaml.github.io/odoc/odoc/odoc.html/), [`odoc.latex`](https://ocaml.github.io/odoc/odoc/odoc.latex/), and [`odoc.manpage`](https://ocaml.github.io/odoc/odoc/odoc.manpage/).
104
105### CLI and Driver
106
107The CLI for `odoc` and various helper functions for driving the process are contained in the [`odoc.odoc`](https://ocaml.github.io/odoc/odoc/odoc.odoc/) library.
108
109### Test and Internal Libraries
110
111There are a couple of libraries used internally for testing - [`odoc.xref_test`](https://ocaml.github.io/odoc/odoc/odoc.xref_test/) and [`odoc.model_desc`](https://ocaml.github.io/odoc/odoc/odoc.model_desc/).
112
113## Dependency Libraries
114
115There are several [dependency libraries](https://github.com/ocaml/odoc/blob/b8c8d99e85b90da8bc31c7a7e5e94d4daa653ab1/odoc.opam#L42) that `odoc` uses, whose functions, type, and module declarations are essential for understanding how `odoc` works. See the [driver](https://ocaml.github.io/odoc/odoc/driver.html) page for details on how the documentation for these libraries are included.