1OCAMLDOC(1) General Commands Manual OCAMLDOC(1)
2
3
4
6 ocamldoc - The OCaml documentation generator
7
8
9
11 ocamldoc [ options ] filename ...
12
13
15 The OCaml documentation generator ocamldoc(1) generates documentation
16 from special comments embedded in source files. The comments used by
17 ocamldoc are of the form (** ... *) and follow the format described in
18 the The OCaml user's manual.
19
20 ocamldoc can produce documentation in various formats: HTML, LaTeX,
21 TeXinfo, Unix man pages, and dot(1) dependency graphs. Moreover, users
22 can add their own custom generators.
23
24 In this manpage, we use the word element to refer to any of the follow‐
25 ing parts of an OCaml source file: a type declaration, a value, a mod‐
26 ule, an exception, a module type, a type constructor, a record field, a
27 class, a class type, a class method, a class value or a class inheri‐
28 tance clause.
29
30
32 The following command-line options determine the format for the gener‐
33 ated documentation generated by ocamldoc(1).
34
35 Options for choosing the output format
36 -html Generate documentation in HTML default format. The generated
37 HTML pages are stored in the current directory, or in the direc‐
38 tory specified with the -d option. You can customize the style
39 of the generated pages by editing the generated style.css file,
40 or by providing your own style sheet using option -css-style.
41 The file style.css is not generated if it already exists.
42
43 -latex Generate documentation in LaTeX default format. The generated
44 LaTeX document is saved in file ocamldoc.out, or in the file
45 specified with the -o option. The document uses the style file
46 ocamldoc.sty. This file is generated when using the -latex
47 option, if it does not already exist. You can change this file
48 to customize the style of your LaTeX documentation.
49
50 -texi Generate documentation in TeXinfo default format. The generated
51 LaTeX document is saved in file ocamldoc.out, or in the file
52 specified with the -o option.
53
54 -man Generate documentation as a set of Unix man pages. The generated
55 pages are stored in the current directory, or in the directory
56 specified with the -d option.
57
58 -dot Generate a dependency graph for the toplevel modules, in a for‐
59 mat suitable for displaying and processing by dot(1). The
60 dot(1) tool is available from https://graphviz.org/. The tex‐
61 tual representation of the graph is written to the file ocaml‐
62 doc.out, or to the file specified with the -o option. Use
63 dot ocamldoc.out to display it.
64
65 -g file
66 Dynamically load the given file (which extension usually is .cmo
67 or .cma), which defines a custom documentation generator. If
68 the given file is a simple one and does not exist in the current
69 directory, then ocamldoc looks for it in the custom generators
70 default directory, and in the directories specified with the -i
71 option.
72
73 -customdir
74 Display the custom generators default directory.
75
76 -i directory
77 Add the given directory to the path where to look for custom
78 generators.
79
80 General options
81 -d dir Generate files in directory dir, rather than the current direc‐
82 tory.
83
84 -dump file
85 Dump collected information into file. This information can be
86 read with the -load option in a subsequent invocation of ocaml‐
87 doc(1).
88
89 -hide modules
90 Hide the given complete module names in the generated documenta‐
91 tion. modules is a list of complete module names are separated
92 by commas (,), without blanks. For instance: Stdlib,M2.M3.
93
94 -inv-merge-ml-mli
95 Reverse the precedence of implementations and interfaces when
96 merging. All elements in implementation files are kept, and the
97 -m option indicates which parts of the comments in interface
98 files are merged with the comments in implementation files.
99
100 -keep-code
101 Always keep the source code for values, methods and instance
102 variables, when available. The source code is always kept when a
103 .ml file is given, but is by default discarded when a .mli is
104 given. This option allows the source code to be always kept.
105
106 -load file
107 Load information from file, which has been produced by ocaml‐
108 doc -dump. Several -load options can be given.
109
110 -m flags
111 Specify merge options between interfaces and implementations.
112 flags can be one or several of the following characters:
113
114 d merge description
115
116 a merge @author
117
118 v merge @version
119
120 l merge @see
121
122 s merge @since
123
124 o merge @deprecated
125
126 p merge @param
127
128 e merge @raise
129
130 r merge @return
131
132 A merge everything
133
134 -no-custom-tags
135 Do not allow custom @-tags.
136
137 -no-stop
138 Keep elements placed after the (**/**) special comment.
139
140 -o file
141 Output the generated documentation to file instead of ocaml‐
142 doc.out. This option is meaningful only in conjunction with the
143 -latex, -texi, or -dot options.
144
145 -open module
146 Opens module before typing.
147
148 -pp command
149 Pipe sources through preprocessor command.
150
151 -ppx command
152 Pipe abstract syntax tree through preprocessor command.
153
154 -show-missed-crossref
155 Show missed cross-reference opportunities.
156
157 -sort Sort the list of top-level modules before generating the docu‐
158 mentation.
159
160 -stars Remove blank characters until the first asterisk ('*') in each
161 line of comments.
162
163 -t title
164 Use title as the title for the generated documentation.
165
166 -text file
167 Consider file as a .txt file.
168
169 -intro file
170 Use content of file as ocamldoc text to use as introduction
171 (HTML, LaTeX and TeXinfo only). For HTML, the file is used to
172 create the whole "index.html" file.
173
174 -v Verbose mode. Display progress information.
175
176 -version
177 Print version string and exit.
178
179 -vnum Print short version number and exit.
180
181 -warn-error
182 Treat ocamldoc warnings as errors.
183
184 -hide-warnings
185 Do not print ocamldoc warnings.
186
187 -help or --help
188 Display a short usage summary and exit.
189
190 Type-checking options
191 ocamldoc(1) calls the OCaml type-checker to obtain type information.
192 The following options impact the type-checking phase. They have the
193 same meaning as for the ocamlc(1) and ocamlopt(1) commands.
194
195 -I directory
196 Add directory to the list of directories search for compiled
197 interface files (.cmi files).
198
199 -nolabels
200 Ignore non-optional labels in types.
201
202 -rectypes
203 Allow arbitrary recursive types. (See the -rectypes option to
204 ocamlc(1).)
205
206 Options for generating HTML pages
207 The following options apply in conjunction with the -html option:
208
209 -all-params
210 Display the complete list of parameters for functions and meth‐
211 ods.
212
213 -charset s
214 Add information about character encoding being s (default is
215 iso-8859-1).
216
217 -css-style filename
218 Use filename as the Cascading Style Sheet file.
219
220 -colorize-code
221 Colorize the OCaml code enclosed in [ ] and \{[ ]\}, using col‐
222 ors to emphasize keywords, etc. If the code fragments are not
223 syntactically correct, no color is added.
224
225 -index-only
226 Generate only index files.
227
228 -short-functors
229 Use a short form to display functors: module M : functor (A:Mod‐
230 ule) -> functor (B:Module2) -> sig .. end is displayed as module
231 M (A:Module) (B:Module2) : sig .. end.
232
233 Options for generating LaTeX files
234 The following options apply in conjunction with the -latex option:
235
236 -latex-value-prefix prefix
237 Give a prefix to use for the labels of the values in the gener‐
238 ated LaTeX document. The default prefix is the empty string. You
239 can also use the options -latex-type-prefix, -latex-exception-
240 prefix, -latex-module-prefix, -latex-module-type-prefix, -latex-
241 class-prefix, -latex-class-type-prefix, -latex-attribute-pre‐
242 fix, and -latex-method-prefix.
243
244 These options are useful when you have, for example, a type and
245 a value with the same name. If you do not specify prefixes,
246 LaTeX will complain about multiply defined labels.
247
248 -latextitle n,style
249 Associate style number n to the given LaTeX sectioning command
250 style, e.g. sectionorsubsection. (LaTeX only.) This is useful
251 when including the generated document in another LaTeX document,
252 at a given sectioning level. The default association is 1 for
253 section, 2 for subsection, 3 for subsubsection, 4 for paragraph
254 and 5 for subparagraph.
255
256 -noheader
257 Suppress header in generated documentation.
258
259 -notoc Do not generate a table of contents.
260
261 -notrailer
262 Suppress trailer in generated documentation.
263
264 -sepfiles
265 Generate one .tex file per toplevel module, instead of the
266 global ocamldoc.out file.
267
268 Options for generating TeXinfo files
269 The following options apply in conjunction with the -texi option:
270
271 -esc8 Escape accented characters in Info files.
272
273 -info-entry
274 Specify Info directory entry.
275
276 -info-section
277 Specify section of Info directory.
278
279 -noheader
280 Suppress header in generated documentation.
281
282 -noindex
283 Do not build index for Info files.
284
285 -notrailer
286 Suppress trailer in generated documentation.
287
288 Options for generating dot graphs
289 The following options apply in conjunction with the -dot option:
290
291 -dot-colors colors
292 Specify the colors to use in the generated dot code. When gener‐
293 ating module dependencies, ocamldoc(1) uses different colors for
294 modules, depending on the directories in which they reside. When
295 generating types dependencies, ocamldoc(1) uses different colors
296 for types, depending on the modules in which they are defined.
297 colors is a list of color names separated by commas (,), as in
298 Red,Blue,Green. The available colors are the ones supported by
299 the dot(1) tool.
300
301 -dot-include-all
302 Include all modules in the dot(1) output, not only modules given
303 on the command line or loaded with the -load option.
304
305 -dot-reduce
306 Perform a transitive reduction of the dependency graph before
307 outputting the dot code. This can be useful if there are a lot
308 of transitive dependencies that clutter the graph.
309
310 -dot-types
311 Output dot code describing the type dependency graph instead of
312 the module dependency graph.
313
314 Options for generating man files
315 The following options apply in conjunction with the -man option:
316
317 -man-mini
318 Generate man pages only for modules, module types, classes and
319 class types, instead of pages for all elements.
320
321 -man-suffix suffix
322 Set the suffix used for generated man filenames. Default is o,
323 as in List.o.
324
325 -man-section section
326 Set the section number used for generated man filenames. Default
327 is 3.
328
329
330
332 ocaml(1), ocamlc(1), ocamlopt(1).
333 The OCaml user's manual, chapter "The documentation generator".
334
335
336
337 OCAMLDOC(1)