Merge branch 'master' into gh-issue-1043

CHANGES.md

@@ -29,6 +29,9 @@ Tags:
 ### Changed
 - Style: Remove font fallback to Helvetica, Arial (@Julow, #1028)
 
+### Changed
+- Style: Adjusted line height in the TOC to improve readability (@sorawee, #1045)
+
 ### Fixed
 - Warn and exit when table(s) is not closed (@lubegasimon, #1050)
 

doc/parent_child_spec.mld

@@ -1,6 +1,8 @@
 {0 Parent/Child Specification}
 This parent/child specification allows more flexible output support, e.g., per library documentation. See {{:https://ocaml.org/packages}ocaml.org/packages}.
 
+{1 Rules}
+
 The rules are;
 
 {ul 
@@ -19,6 +21,8 @@ The rules are;
 {b Note:} The [--pkg <package>] option is still supported for backward compatibility in [odoc >= v2.0.0],
 although it's now equivalent to specifying a parent [.mld] file.
 
+{1 Example}
+
 For example, let's consider [John] whose is [Doe] and [Mark]'s father. [Doe] has
 children, [Max], and page [foo], whereas [Mark] has no children. That is to say,
 [john.mld], [doe.mld], [mark.mld], [max.mld], [foo.ml] respectively. For instance;
@@ -157,3 +161,31 @@ and we shall get
 ]}
 
 For more about [odoc] commands, simply invoke [odoc --help] in your shell.
+
+{1 Convention for installed packages}
+
+Locally, the build system can make arbitrary complex documentation page
+hierarchies.
+However, the generated HTML documentation is generally not installed as part of
+a package. Instead the documentation source code made of [.mld] pages is
+installed and might be used by a different driver.
+
+{2 Convention}
+
+In order for drivers to build consistent documentation for a package, the
+following convention should be followed.
+
+- [.mld] pages are installed in a package's [share] directory, under the
+  [odoc-pages] sub-directory.
+- A page is the parent of every installed pages. The driver can freely name this
+  page, for example it can be named after the package. In what follows, we
+  refer to this page as the [pkg] page.
+- If there is an installed [index.mld] file, the driver has to use it as
+  content for the [pkg] page.
+- If there is no installed [index.mld] page, the driver has to generate some
+  content for the [pkg] page.
+
+This convention is followed by the
+{{:https://github.com/ocaml-doc/voodoo}driver for ocaml.org},
+by the driver {{:https://erratique.ch/software/odig/doc/packaging.html}Odig}
+and by the build system {{:https://github.com/ocaml/dune}Dune}.

src/compat/dune

@@ -1,3 +1,7 @@
 (library
  (name compatcmdliner)
- (libraries cmdliner))
+ (libraries cmdliner)
+ (instrumentation
+  (backend landmarks --auto))
+ (instrumentation
+  (backend bisect_ppx)))

src/document/dune

@@ -12,4 +12,6 @@
  (public_name odoc.document)
  (instrumentation
   (backend bisect_ppx))
+ (instrumentation
+  (backend landmarks --auto))
  (libraries odoc_model fpath astring syntax_highlighter))

src/html/dune

@@ -1,6 +1,8 @@
 (library
  (name odoc_html)
  (public_name odoc.html)
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx))
  (libraries odoc_model odoc_document tyxml))

src/html_support_files/dune

@@ -37,6 +37,10 @@
 (library
  (name odoc_html_support_files)
  (public_name odoc.html_support_files)
+ (instrumentation
+  (backend landmarks --auto))
+ (instrumentation
+  (backend bisect_ppx))
  (wrapped false))
 
 (install

src/html_support_files/odoc.css

@@ -779,7 +779,7 @@ td.def-doc *:first-child {
   font-size: 0.95em;
   color: var(--color);
   font-weight: 400;
-  line-height: 1.6em;
+  line-height: 1.2em;
   display: block;
 }
 
@@ -1070,14 +1070,15 @@ td.def-doc *:first-child {
 
 .odoc-toc li ul {
   margin: 0px;
+  padding-top: 0.25em;
 }
 
 .odoc-toc ul {
   list-style-type: none;
 }
 
 .odoc-toc ul li {
-  margin: 0;
+  padding: 0.25em 0;
 }
 
 .odoc-toc>ul>li {

src/latex/dune

@@ -1,6 +1,8 @@
 (library
  (name odoc_latex)
  (public_name odoc.latex)
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx))
  (libraries odoc_model odoc_document fmt fpath))

src/manpage/dune

@@ -1,6 +1,8 @@
 (library
  (name odoc_manpage)
  (public_name odoc.manpage)
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx))
  (libraries odoc_model odoc_document))

src/model/dune

@@ -12,6 +12,8 @@
  (public_name odoc.model)
  (flags
   (:standard -w -50))
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx))
  (libraries result compiler-libs.common odoc-parser))

src/model_desc/dune

@@ -2,5 +2,7 @@
  (name odoc_model_desc)
  (public_name odoc.model_desc)
  (libraries odoc_model)
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx)))

src/odoc/bin/dune

@@ -5,5 +5,7 @@
  (libraries compatcmdliner odoc_model odoc_odoc)
  (flags
   (:standard -open StdLabels))
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx)))

src/odoc/dune

@@ -14,6 +14,8 @@
   odoc_xref2
   tyxml
   unix)
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx)))
 

src/parser/dune

@@ -3,6 +3,8 @@
 (library
  (name odoc_parser)
  (public_name odoc-parser)
+ (instrumentation
+  (backend landmarks --auto))
  (instrumentation
   (backend bisect_ppx))
  (flags

src/parser/test/dune

@@ -3,6 +3,8 @@
  (inline_tests)
  (enabled_if
   (>= %{ocaml_version} 4.04.1))
+ (instrumentation
+  (backend landmarks --auto))
  (preprocess
   (pps ppx_expect))
  (libraries sexplib0 odoc-parser))

src/xref2/dune

@@ -1,11 +1,22 @@
 (library
  (name odoc_xref2)
  (public_name odoc.xref2)
- (preprocess
-  (action
-   (run %{bin:cppo} -V OCAML:%{ocaml_version} %{input-file})))
+ (instrumentation
+  (backend landmarks --auto))
+ (instrumentation
+  (backend bisect_ppx))
  (libraries odoc_model))
 
+(rule
+ (with-stdout-to
+  shape_tools.ml
+  (run %{bin:cppo} -V OCAML:%{ocaml_version} %{dep:shape_tools.cppo.ml})))
+
+(rule
+ (with-stdout-to
+  shape_tools.mli
+  (run %{bin:cppo} -V OCAML:%{ocaml_version} %{dep:shape_tools.cppo.mli})))
+
 (rule
  (alias runmdx)
  (deps