Parent

CHANGES.md

@@ -11,6 +11,7 @@
 - Navigation for the search bar : use '/' to enter search, up and down arrows to
   select a result, and enter to follow the selected link. (@EmileTrotignon, #1088)
 - OCaml 5.2.0 compatibility (@Octachron, #1094, #1112)
+- New driver package (@jonludlam, #1121)
 
 ### Changed
 

doc/cheatsheet.mld

@@ -0,0 +1,225 @@
+{0 Cheatsheet}
+
+Quick reference for the odoc language!
+
+{table
+  {tr
+    {th }
+    {th [odoc] syntax}
+    {th Render as}}
+  {tr
+    {th Paragraphs}
+    {td {@text[
+      A first paragraph
+
+      A second paragraph]}}
+    {td
+      A first paragraph
+
+      A second paragraph}}
+  {tr
+    {th {{!odoc_for_authors.sections}Headings}}
+    {td {@text[
+      {1 Title}
+      {2 Subtitle}
+      {3 Subsubtitle}
+
+      {3:my_id Referenceable title}
+
+      See {!my_id}.
+      ]}
+
+      Standalone pages must start with a [0] heading:
+
+      {@text[
+        {0 Page big title}
+      ]}}
+    {td
+      {%html:<h1>Title</h1>%}
+      {%html:<h2>Subtitle</h2>%}
+      {%html:<h3>Subsubtitle</h3>%}
+      {%html:<h3 id="my_id">Referenceable title</h3>%}
+
+      See {%html:<a href="#my_id">Referenceable title</a>%}}}
+  {tr
+    {th {{!odoc_for_authors.basics}Bold, italic and emphasis}}
+    {td {@text[{b bold} text, {e italic text}, {e emphasized} text]}}
+    {td   {b bold} text, {e italic text}, {e emphasized} text}}
+  {tr
+    {th {{!odoc_for_authors.basics}Subscripts and superscript}}
+    {td {@text[H{_ 2}O and 1{^ st}]}}
+    {td   H{_ 2}O and 1{^ st}}}
+  {tr
+    {th {{!odoc_for_authors.links_and_references}Link} }
+    {td {@text[
+      Here is a link: {:https://www.example.com}.
+
+      You can also click {{:https://www.example.com}here}.]}}
+    {td
+      Here is a link: {:https://www.example.com}.
+
+      You can also click {{:https://www.example.com}here}.}}
+  {tr
+    {th {{!odoc_for_authors.links_and_references}References} }
+    {td {@text[
+      See {!Odoc_odoc.Compile.compile}.
+
+      See {{!Odoc_odoc.Compile.compile}this function}.
+
+      See {{!odoc_for_authors.links_and_references}this section} for the syntax of references.]}}
+    {td
+      See {!Odoc_odoc.Compile.compile}.
+
+      See {{!Odoc_odoc.Compile.compile}this function}.
+
+      See {{!odoc_for_authors.links_and_references}this section} for the syntax of references.}}
+    {tr
+      {th {{!odoc_for_authors.lists}Lists} }
+    {td {@text[
+      - First item
+      - Second item
+
+      + First ordered item
+      + Second numbered item
+
+      {ul
+        {- First item}
+        {- Second item}
+        {li can also be used}}
+
+      {ol
+        {- First numbered item}
+        {- Second numbered item}
+        {li can also be used}}]}}
+    {td
+      - First item
+      - Second item
+
+      + First ordered item
+      + Second numbered item
+
+      {ul
+        {- First item}
+        {- Second item}
+        {li can also be used}}
+
+      {ol
+        {- First numbered item}
+        {- Second numbered item}
+        {li can also be used}}}}
+  {tr
+    {th {{!odoc_for_authors.code_blocks}Code Blocks} }
+    {td {example@text[
+      Inline [code].
+
+      {[
+        let _ = "Block code"
+      ]}
+
+      {foo@text[
+        Code block with {[inner code block syntax]}
+      ]foo}
+
+      {@python[
+        [i+1 for i in xrange(2)]
+      ]}]example}}
+    {td
+
+      Inline [code].
+
+      {[
+        let _ = "Block code"
+      ]}
+
+      {foo@text[
+        Code block with {[inner code block syntax]}
+      ]foo}
+
+      {@python[
+        [i+1 for i in xrange(2)]
+      ]}}}
+  {tr
+    {th {{!odoc_for_authors.verbatim_blocks}Verbatim} }
+    {td {example@text[
+      {v verbatim text v}]example}}
+    {td {v verbatim text v}}}
+  {tr
+    {th {{!odoc_for_authors.math}Math} }
+    {td {@text[
+      For inline math: {m \sqrt 2}.
+
+      For display math:
+
+      {math \sqrt 2}]}}
+    {td
+      For inline math: {m \sqrt 2}.
+
+      For display math:
+
+      {math \sqrt 2}}}
+  {tr
+    {th {{!odoc_for_authors.tables}Table} }
+    {td {@text[
+      Light syntax:
+
+      {t | Header 1 | Header 2 |
+         |----------|----------|
+         | Cell 1   | Cell 2   |
+         | Cell 3   | Cell 4   |}
+
+      Explicit syntax:
+
+      {table
+        {tr
+          {th Header 1}
+          {th Header 2}}
+        {tr
+          {td Cell 1}
+          {td Cell 2}}
+        {tr
+          {td Cell 3}
+          {td Cell 4}}}]}}
+    {td
+      Light syntax:
+
+      {t | Header 1 | Header 2 |
+         |----------|----------|
+         | Cell 1   | Cell 2   |
+         | Cell 3   | Cell 4   |}
+
+      Explicit syntax:
+
+      {table
+        {tr
+          {th Header 1}
+          {th Header 2}}
+        {tr
+          {td Cell 1}
+          {td Cell 2}}
+        {tr
+          {td Cell 3}
+          {td Cell 4}}}}}
+  {tr
+    {th HTML }
+    {td {example@text[
+      {%html:
+        <blockquote>
+          Odoc language lack support for quotation!
+        </blockquote>
+      %}]example}}
+    {td
+      {%html:
+        <blockquote>
+          Odoc language lack support for quotation!
+        </blockquote>
+      %}}}
+  {tr
+    {th {{!page-odoc_for_authors.tags}Tags} }
+    {td {example@text[
+      @since 4.08
+
+      Tags are explained in {{!page-odoc_for_authors.tags}this section}.]example}}
+    {td
+      Since 4.08.
+
+      Tags are explained in {{!page-odoc_for_authors.tags}this section}.}}}

doc/driver.mld

@@ -394,6 +394,7 @@ let extra_docs = [
     "parent_child_spec";
     "features";
     "odoc_for_authors";
+    "cheatsheet";
     "dune";
     "ocamldoc_differences";
     "api_reference";

doc/dune

@@ -8,6 +8,7 @@
   interface
   ocamldoc_differences
   odoc_for_authors
+  cheatsheet
   parent_child_spec))
 
 ; Uncomment to run mdx on the documentation's code blocks.

doc/odoc.mld

@@ -1,5 +1,7 @@
 {0 odoc}
 
+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
@@ -47,6 +49,7 @@ setting, you'll need to understand {{!page-driver}how to drive [odoc]}.
 
 The main other pages of this site:
 - {!page-odoc_for_authors} Odoc For Authors
+- {!page-cheatsheet} The cheatsheet
 - {!page-features} Language Features
 - {!page-driver} Reference Driver
 - {!page-ocamldoc_differences} Differences from OCamldoc

doc/odoc_for_authors.mld

@@ -227,7 +227,7 @@ There are no differences in how [odoc] handles comment placement between [.ml]
 and [.mli] files, which is {{!page-ocamldoc_differences}another difference}
 from OCamldoc.
 
-{2 Basic markup}
+{2:basics Basic markup}
 
 Text within the comments can be formatted using the following markup. Firstly,
 the simple typesetting markup:
@@ -363,7 +363,7 @@ In a code block section, the section is ended with a [ \]} ], and in a
 verbatim formatted section, the section is ended with a whitespace character
 followed by [ v} ]. It is not currently possible to escape this in either case.
 
-{2 Links and References}
+{2:links_and_references Links and References}
 
 A link to a URL may be put into the text as follows:
 
@@ -480,7 +480,7 @@ unit or page must be {e compiled} and available to [odoc]. That is, when perform
 [-I] must contain the relevant [.odoc] file. This is normally the responsibility of
 the {{!page-driver}driver}.
 
-{2 Tags}
+{2:tags Tags}
 
 Tags are used to provide specific information for individual elements, such
 as author, version, parameters, etc. Tags start with an [@] symbol, appear
@@ -542,7 +542,7 @@ doesn't turn this into a link in the output HTML.
 (written between double quotes), with the given text as comment. {e Note:} 
 As with the file reference, [odoc] doesn't turn this into a link.
 
-{2 Mathematics}
+{2:math Mathematics}
 
 Odoc 2.2 introduced new markup for maths, available both for inline and block
 content. The syntax for the maths itself is LaTeX and it is rendered by {{:https://katex.org/}KaTeX}
@@ -559,7 +559,7 @@ in block form this becomes:
 See the {{:https://katex.org/docs/supported.html}KaTeX documentation} for the
 HTML mode LaTeX support status.
 
-{2 Tables}
+{2:tables Tables}
 
 Odoc 2.3 introduced new markup for tables. This markup comes in two flavors: the light syntax, and the heavy syntax.
 

odoc-driver.opam

@@ -0,0 +1,59 @@
+opam-version: "2.0"
+
+version: "dev"
+homepage: "https://github.com/ocaml/odoc"
+doc: "https://ocaml.github.io/odoc/"
+bug-reports: "https://github.com/ocaml/odoc/issues"
+license: "ISC"
+
+maintainer: [
+  "Daniel Bünzli <[email protected]>"
+  "Jon Ludlam <[email protected]>"
+  "Jules Aguillon <[email protected]>"
+  "Paul-Elliot Anglès d'Auriac <[email protected]>"
+]
+authors: [
+  "Anton Bachin <[email protected]>"
+  "Daniel Bünzli <[email protected]>"
+  "David Sheets <[email protected]>"
+  "Jon Ludlam <[email protected]>"
+  "Jules Aguillon <[email protected]>"
+  "Leo White <[email protected]>"
+  "Lubega Simon <[email protected]>"
+  "Paul-Elliot Anglès d'Auriac <[email protected]>"
+  "Thomas Refis <[email protected]>"
+]
+dev-repo: "git+https://github.com/ocaml/odoc.git"
+
+synopsis: "OCaml Documentation Generator - Driver"
+description: """
+The driver is a sample implementation of a tool to drive odoc to generate
+documentation for installed packages.
+"""
+
+
+depends: [
+  "odoc" {= version}
+  "bos" 
+  "fpath"
+  "yojson"
+  "ocamlfind"
+  "opam-format"
+  "logs"
+  "eio_main"
+]
+
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]

src/.ocamlformat-ignore

@@ -13,4 +13,5 @@ syntax_highlighter/syntax_highlighter.ml
 model/*.cppo.ml
 html_support_files/*.ml
 xref2/shape_tools.*
+odoc/classify.cppo.ml