diff --git a/doc/index.mld b/doc/index.mld deleted file mode 120000 index 27eba18474..0000000000 --- a/doc/index.mld +++ /dev/null @@ -1 +0,0 @@ -odoc.mld \ No newline at end of file diff --git a/doc/index.mld b/doc/index.mld new file mode 100644 index 0000000000..fffd805ca5 --- /dev/null +++ b/doc/index.mld @@ -0,0 +1,51 @@ +@children_order odoc_for_authors cheatsheet dune features ocamldoc_differences interface driver json deprecated/ +@short_title The odoc documentation generator + +{0 The [odoc] documentation generator} + +{audio:https://choum.net/panglesd/odoc.mp3} + +{b For a quick look at the [odoc] syntax, see the {{!cheatsheet}cheatsheet}!} + +{1:overview What is [odoc]?} + +[odoc] is a documentation generator for OCaml. It reads doc comments +from your source files and your [.mld] files, then outputs HTML, LaTeX and +man pages. The pages you are reading now are rendered using [odoc]. + +Text inside doc comments (delimited by [(** ... *)]) is marked up in +[odoc] syntax: + +{[ +val float_dsig : int -> float t +(** [float_dsig d] rounds the normalised {e decimal} significand + of the float to the [d]th decimal fractional digit and formats + the result with ["%g"]. Ties are rounded towards positive + infinity. The result is NaN on infinities and only defined for + [0 <= d <= 16]. + + {b Warning.} The current implementation overflows on large [d] + and floats. *) +]} + +These comments are picked up by [odoc] and {{!Fmt.float_dsig}turned into HTML}, LaTeX, or manpages. + +The syntax reference is a refinement of that explained in the +{{:https://ocaml.org/manual/ocamldoc.html}OCaml manual}. The differences +are described {{!page-ocamldoc_differences}here}. + +[odoc]'s main advantages over OCamldoc are: + +- an accurate {e cross-referencer} that can calculate links between types, modules, +module types, and more. So if you've ever been baffled by exactly what the [t] was in [val f : A(M).t -> unit], [odoc] will link to it! +- an {e expander}, which can expand complex module-type expressions while preserving their structure, including comment, includes, and +more. If you've ever wondered what values there are in your module [M : Base.Applicative.S with type t := u], [odoc] will show you! + +{1 For Authors} + +For guidance on how to document your OCaml project, see {!page-odoc_for_authors}. + +{1 For Integrators} + +To integrate [odoc] into your tool, webpage or any other +setting, you'll need to understand {{!page-driver}how to drive [odoc]}. diff --git a/doc/odoc.mld b/doc/odoc.mld deleted file mode 100644 index fffd805ca5..0000000000 --- a/doc/odoc.mld +++ /dev/null @@ -1,51 +0,0 @@ -@children_order odoc_for_authors cheatsheet dune features ocamldoc_differences interface driver json deprecated/ -@short_title The odoc documentation generator - -{0 The [odoc] documentation generator} - -{audio:https://choum.net/panglesd/odoc.mp3} - -{b For a quick look at the [odoc] syntax, see the {{!cheatsheet}cheatsheet}!} - -{1:overview What is [odoc]?} - -[odoc] is a documentation generator for OCaml. It reads doc comments -from your source files and your [.mld] files, then outputs HTML, LaTeX and -man pages. The pages you are reading now are rendered using [odoc]. - -Text inside doc comments (delimited by [(** ... *)]) is marked up in -[odoc] syntax: - -{[ -val float_dsig : int -> float t -(** [float_dsig d] rounds the normalised {e decimal} significand - of the float to the [d]th decimal fractional digit and formats - the result with ["%g"]. Ties are rounded towards positive - infinity. The result is NaN on infinities and only defined for - [0 <= d <= 16]. - - {b Warning.} The current implementation overflows on large [d] - and floats. *) -]} - -These comments are picked up by [odoc] and {{!Fmt.float_dsig}turned into HTML}, LaTeX, or manpages. - -The syntax reference is a refinement of that explained in the -{{:https://ocaml.org/manual/ocamldoc.html}OCaml manual}. The differences -are described {{!page-ocamldoc_differences}here}. - -[odoc]'s main advantages over OCamldoc are: - -- an accurate {e cross-referencer} that can calculate links between types, modules, -module types, and more. So if you've ever been baffled by exactly what the [t] was in [val f : A(M).t -> unit], [odoc] will link to it! -- an {e expander}, which can expand complex module-type expressions while preserving their structure, including comment, includes, and -more. If you've ever wondered what values there are in your module [M : Base.Applicative.S with type t := u], [odoc] will show you! - -{1 For Authors} - -For guidance on how to document your OCaml project, see {!page-odoc_for_authors}. - -{1 For Integrators} - -To integrate [odoc] into your tool, webpage or any other -setting, you'll need to understand {{!page-driver}how to drive [odoc]}. diff --git a/test/generators/html/fonts b/test/generators/html/fonts deleted file mode 120000 index d23f5f26f1..0000000000 --- a/test/generators/html/fonts +++ /dev/null @@ -1 +0,0 @@ -../../../src/html_support_files/fonts \ No newline at end of file diff --git a/test/generators/html/highlight.pack.js b/test/generators/html/highlight.pack.js deleted file mode 120000 index 3594f0715a..0000000000 --- a/test/generators/html/highlight.pack.js +++ /dev/null @@ -1 +0,0 @@ -../../../src/html_support_files/highlight.pack.js \ No newline at end of file diff --git a/test/generators/html/katex.min.css b/test/generators/html/katex.min.css deleted file mode 120000 index e5673575fc..0000000000 --- a/test/generators/html/katex.min.css +++ /dev/null @@ -1 +0,0 @@ -../../../src/html_support_files/katex.min.css \ No newline at end of file diff --git a/test/generators/html/katex.min.js b/test/generators/html/katex.min.js deleted file mode 120000 index f94abf9614..0000000000 --- a/test/generators/html/katex.min.js +++ /dev/null @@ -1 +0,0 @@ -../../../src/html_support_files/katex.min.js \ No newline at end of file diff --git a/test/generators/html/odoc.css b/test/generators/html/odoc.css deleted file mode 120000 index c32dbe9235..0000000000 --- a/test/generators/html/odoc.css +++ /dev/null @@ -1 +0,0 @@ -../../../src/html_support_files/odoc.css \ No newline at end of file