|
1 | 1 | # odoc [](https://ci.ocamllabs.io/github/ocaml/odoc) [](https://coveralls.io/github/ocaml/odoc) |
2 | 2 |
|
3 | 3 | **odoc** is a documentation generator for OCaml. It reads *doc comments* , |
4 | | -delimited with `(** ... *)`, and outputs HTML. |
5 | | -See [example output][odig-sample]. |
6 | | - |
7 | | -[odig-sample]: https://b0-system.github.io/odig/doc/index.html |
8 | | - |
9 | | -Text inside doc comments is marked up in ocamldoc syntax: |
10 | | - |
11 | | -```ocaml |
12 | | -val compare : string -> string -> int |
13 | | -(** [compare s1 s2] compares [s1] and [s2] in {e lexicographic} order. The |
14 | | - result is negative if [s1] precedes [s2], positive if [s1] follows [s2], |
15 | | - and zero if [s1] and [s2] are equal. *) |
16 | | -``` |
17 | | - |
18 | | -The syntax reference is [here][comment-syntax]. There is also an |
19 | | -[explanation][comment-location] of how to attach comments to specific types, |
20 | | -values, and other elements in your program. |
21 | | - |
22 | | -[comment-syntax]: http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-syntax |
23 | | -[comment-location]: http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-placement |
24 | | - |
25 | | -<br/> |
26 | | - |
27 | | -odoc's main advantage over ocamldoc is an accurate cross-referencer, which |
28 | | -handles the complexity of the OCaml module system. odoc also offers a good |
29 | | -opportunity to improve HTML output compared to ocamldoc, but this is very much |
30 | | -a work in progress :) |
31 | | - |
32 | | -<br/> |
| 4 | +delimited with `(** ... *)`, and outputs HTML, LaTeX and man pages. |
33 | 5 |
|
34 | 6 | ## Using `odoc` with OCaml |
35 | 7 |
|
36 | 8 | To install odoc with opam: |
37 | 9 |
|
38 | 10 | ``` |
39 | | -opam install odoc |
40 | | -``` |
41 | | - |
42 | | -If you want to use odoc on the packages you have installed in your |
43 | | -opam switch type: |
44 | | - |
45 | | -``` |
46 | | -opam install ocaml-manual odig |
47 | | -odig doc |
| 11 | +$ opam install odoc |
48 | 12 | ``` |
49 | 13 |
|
50 | | -When you are developing the easiest way to use odoc right now is by |
51 | | -having Dune drive it. This command should work in most Dune projects |
52 | | -out of the box: |
| 14 | +For more information, see the [odoc website](https://ocaml.github.io/odoc) or build |
| 15 | +the docs locally yourself from the `odoc` directory: |
53 | 16 |
|
54 | 17 | ``` |
55 | | -dune build @doc |
| 18 | +git clone https://github.com/ocaml/odoc.git |
| 19 | +cd odoc |
| 20 | +opam pin add . -n |
| 21 | +opam install mdx bos |
| 22 | +opam install --deps-only -t odoc |
| 23 | +dune build @docgen |
56 | 24 | ``` |
57 | 25 |
|
58 | | -The generated docs can then be found locally at |
59 | | -`./_build/default/_doc/_html/index.html`. |
60 | | - |
61 | | -<br/> |
62 | | - |
63 | | -## Using `odoc` with BuckleScript/Reason |
64 | | - |
65 | | -You can use the [`bsdoc`](https://reasonml-community.github.io/bsdoc) npm package to use |
66 | | -`odoc` in your BuckleScript projects. |
67 | | - |
68 | | -<br/> |
69 | | - |
70 | | -## Contact |
71 | | - |
72 | | -odoc is most discussed on [discuss.ocaml.org's Ecosystem category][discourse] with the `odoc` tag. |
73 | | -Please also don't hesitate to [open an issue][issues]. |
74 | | - |
75 | | -<br/> |
76 | | - |
77 | | -## Contributing |
78 | | - |
79 | | -Any [question asked](#contact), [issue opened][issues], feedback offered, is a |
80 | | -contribution to odoc, and the project and all its users are thankful :) If |
81 | | -you'd like to contribute code specifically, you may find the guide in |
82 | | -[`CONTRIBUTING.md`][contributing.md] helpful. Also see the [roadmap][roadmap] |
83 | | -there. If anything is missing from it, please don't hesitate to |
84 | | -[reach out](#contact). |
| 26 | +and find the docs in `_build/default/doc/html/index.html` |
85 | 27 |
|
86 | 28 | [discourse]: https://discuss.ocaml.org/c/eco |
87 | 29 | [issues]: https://github.com/ocaml/odoc/issues/new |
|
0 commit comments