Uniform treatment of sidebar

CHANGES.md

@@ -28,10 +28,15 @@
 - Added a `compile-asset` command (@EmileTrotignon, @panglesd, #1170)
 - Allow referencing assets (@panglesd, #1171)
 - Added a `--asset-path` arg to `html-generate` (@panglesd, #1185)
-- Add a `@children_order` tag to specify the order in the sidebar (@panglesd,
-  #1187, #1243)
+- Added a `@children_order` and an `@order_category` tags to specify the order
+  in the sidebar (@panglesd, #1187, #1243, #1251)
 - Add a `@short_title` tag to specify the short title of a page for use in
   the sidebar / breadcrumbs (@panglesd, #1246)
+- Added a home icon in the breacrumbs (@panglesd, #1251)
+- Added a CLI option to add or disable the home icon (@panglesd, #1251)
+- Add sidebar to the implementation pages (@panglesd, #1251)
+- Added a `@toc_status` tag, with possible values `open` and `hidden`, to define
+  the behavior of the entry in the sidebar and breadcrumbs (@panglesd, #1251)
 - Add a frontmatter syntax for mld pages (@panglesd, #1187)
 - Add 'remap' and 'remap-file' options to HTML generation for partial docsets
   (@jonludlam, #1189, #1248)

doc/driver.mld

@@ -124,16 +124,16 @@ A concrete example for such command would be:
   $ odoc compile
        ~/.opam/5.2.0/lib/ppxlib/ppxlib__Extension.cmti
        --output-dir _odoc/
-       -I _odoc/ocaml-base-compiler/lib/compiler-libs.common
-       -I _odoc/ocaml-base-compiler/lib/stdlib
-       -I _odoc/ocaml-compiler-libs/lib/ocaml-compiler-libs.common
-       -I _odoc/ppxlib/lib/ppxlib
-       -I _odoc/ppxlib/lib/ppxlib.ast
-       -I _odoc/ppxlib/lib/ppxlib.astlib
-       -I _odoc/ppxlib/lib/ppxlib.stdppx
-       -I _odoc/ppxlib/lib/ppxlib.traverse_builtins
-       -I _odoc/sexplib0/lib/sexplib0
-       --parent-id ppxlib/lib/ppxlib
+       -I _odoc/ocaml-base-compiler/compiler-libs.common
+       -I _odoc/ocaml-base-compiler/stdlib
+       -I _odoc/ocaml-compiler-libs/ocaml-compiler-libs.common
+       -I _odoc/ppxlib/ppxlib
+       -I _odoc/ppxlib/ppxlib.ast
+       -I _odoc/ppxlib/ppxlib.astlib
+       -I _odoc/ppxlib/ppxlib.stdppx
+       -I _odoc/ppxlib/ppxlib.traverse_builtins
+       -I _odoc/sexplib0/sexplib0
+       --parent-id ppxlib/ppxlib
 ]}
 
 {3 Compiling implementations}
@@ -164,16 +164,16 @@ A concrete example for such command would be:
   $ odoc compile-impl
         ~/.opam/5.2.0/lib/ppxlib/ppxlib__Spellcheck.cmt
         --output-dir _odoc/
-        -I _odoc/ocaml-base-compiler/lib/compiler-libs.common
-        -I _odoc/ocaml-base-compiler/lib/stdlib
-        -I _odoc/ocaml-compiler-libs/lib/ocaml-compiler-libs.common
-        -I _odoc/ppxlib/lib/ppxlib
-        -I _odoc/ppxlib/lib/ppxlib.ast
-        -I _odoc/ppxlib/lib/ppxlib.astlib
-        -I _odoc/ppxlib/lib/ppxlib.stdppx
-        -I _odoc/sexplib0/lib/sexplib0
+        -I _odoc/ocaml-base-compiler/compiler-libs.common
+        -I _odoc/ocaml-base-compiler/stdlib
+        -I _odoc/ocaml-compiler-libs/ocaml-compiler-libs.common
+        -I _odoc/ppxlib/ppxlib
+        -I _odoc/ppxlib/ppxlib.ast
+        -I _odoc/ppxlib/ppxlib.astlib
+        -I _odoc/ppxlib/ppxlib.stdppx
+        -I _odoc/sexplib0/sexplib0
         --enable-missing-root-warning
-        --parent-id ppxlib/lib/ppxlib
+        --parent-id ppxlib/ppxlib
         --source-id ppxlib/src/ppxlib/spellcheck.ml
 ]}
 
@@ -274,18 +274,18 @@ An example of such command:
 {@shell[
   $ odoc compile-index
       -o _odoc/ppxlib/index.odoc-index
-      -P ppxlib:_odoc/ppxlib/doc
-      -L ppxlib:_odoc/ppxlib/lib/ppxlib
-      -L ppxlib.ast:_odoc/ppxlib/lib/ppxlib.ast
-      -L ppxlib.astlib:_odoc/ppxlib/lib/ppxlib.astlib
-      -L ppxlib.metaquot:_odoc/ppxlib/lib/ppxlib.metaquot
-      -L ppxlib.metaquot_lifters:_odoc/ppxlib/lib/ppxlib.metaquot_lifters
-      -L ppxlib.print_diff:_odoc/ppxlib/lib/ppxlib.print_diff
-      -L ppxlib.runner:_odoc/ppxlib/lib/ppxlib.runner
-      -L ppxlib.runner_as_ppx:_odoc/ppxlib/lib/ppxlib.runner_as_ppx
-      -L ppxlib.stdppx:_odoc/ppxlib/lib/ppxlib.stdppx
-      -L ppxlib.traverse:_odoc/ppxlib/lib/ppxlib.traverse
-      -L ppxlib.traverse_builtins:_odoc/ppxlib/lib/ppxlib.traverse_builtins
+      -P ppxlib:_odoc/ppxlib
+      -L ppxlib:_odoc/ppxlib/ppxlib
+      -L ppxlib.ast:_odoc/ppxlib/ppxlib.ast
+      -L ppxlib.astlib:_odoc/ppxlib/ppxlib.astlib
+      -L ppxlib.metaquot:_odoc/ppxlib/ppxlib.metaquot
+      -L ppxlib.metaquot_lifters:_odoc/ppxlib/ppxlib.metaquot_lifters
+      -L ppxlib.print_diff:_odoc/ppxlib/ppxlib.print_diff
+      -L ppxlib.runner:_odoc/ppxlib/ppxlib.runner
+      -L ppxlib.runner_as_ppx:_odoc/ppxlib/ppxlib.runner_as_ppx
+      -L ppxlib.stdppx:_odoc/ppxlib/ppxlib.stdppx
+      -L ppxlib.traverse:_odoc/ppxlib/ppxlib.traverse
+      -L ppxlib.traverse_builtins:_odoc/ppxlib/ppxlib.traverse_builtins
       --occurrences _odoc/occurrences-all.odoc-occurrences
 ]}
 
@@ -354,7 +354,7 @@ An example of such command is:
 
 {@shell[
   $ odoc html-generate
-      _odoc/ppxlib/doc/page-index.odocl
+      _odoc/ppxlib/page-index.odocl
       --index _odoc/ppxlib/index.odoc-index
       --search-uri ppxlib/sherlodoc_db.js
       --search-uri sherlodoc.js
@@ -380,7 +380,7 @@ An example of such command is:
 
 {@shell[
   $ odoc html-generate-source
-      --impl _odoc/ppxlib/lib/ppxlib/impl-ppxlib__Reconcile.odocl
+      --impl _odoc/ppxlib/ppxlib/impl-ppxlib__Reconcile.odocl
       /home/panglesd/.opam/5.2.0/lib/ppxlib/reconcile.ml
       -o _html/
 ]}
@@ -413,27 +413,27 @@ will be used in [--parent-id] and in [-P] and [-L].
 
 The driver can decide any set of mutually disjoint set of roots, without posing
 problem to the reference resolution. For instance, both [-P
-pkg:<output_dir>/pkg/doc] and [-P pkg:<output_dir>/pkg/version/doc] are
+pkg:<output_dir>/pkg] and [-P pkg:<output_dir>/pkg/version] are
 acceptable versions. However, we define here "canonical" roots:
 
-Each installed package [<p>] defines a single page root id: [<p>/doc].
+Each installed package [<p>] defines a single page root id: [<p>].
 
 For each package [<p>], each library [<l>] defines a library root id:
-[<p>/lib/<l>].
+[<p>/<l>].
 
 For instance, a package [foo] with two libraries: [foo] and [foo.bar] will
 define three trees:
 
-- A documentation tree named [foo], with root id [foo/doc]. When referred
-  from other trees, a [-P foo:<odoc_dir>/foo/doc] argument needs to be added
+- A documentation tree named [foo], with root id [foo]. When referred
+  from other trees, a [-P foo:<odoc_dir>/foo] argument needs to be added
   at the link phase.
 
-- A module tree named [foo], with root id [foo/lib/foo]. When referred from
-  other trees, a [-L foo:<odoc_dir>/foo/lib/foo] argument needs to be added
+- A module tree named [foo], with root id [foo/foo]. When referred from
+  other trees, a [-L foo:<odoc_dir>/foo/foo] argument needs to be added
   at the link phase.
 
-- A module tree named [foo.bar], with root id [foo/lib/foo.bar]. When referred from
-  other trees, a [-L foo.bar:<odoc_dir>/foo/lib/foo.bar] argument needs to be
+- A module tree named [foo.bar], with root id [foo/foo.bar]. When referred from
+  other trees, a [-L foo.bar:<odoc_dir>/foo/foo.bar] argument needs to be
   added at the link phase.
 
 {2 Link-time dependencies}
@@ -449,11 +449,11 @@ An installed package [<p>] specifies its tree dependencies in a file at
 
 Stanzas of the form [(packages p1 p2 ...)] specifies that page trees [p1],
 [p2], ..., should be added using the [-P] argument: with the canonical roots, it
-would be [-P p1:<output_dir>/p1/doc -P p2:<output_dir>/p2/doc -P ...].
+would be [-P p1:<output_dir>/p1 -P p2:<output_dir>/p2 -P ...].
 
 Stanzas of the form [(libraries l1 l2 ...)] specifies that module trees [l1],
 [l2], ..., should be added using the [-L] argument: with the canonical roots, it
-would be [-L l1:<output_dir>/p1/lib/l1 -L l2<output_dir>/p2/lib/l2 -L ...],
+would be [-L l1:<output_dir>/p1/l1 -L l2<output_dir>/p2/l2 -L ...],
 where [p1] is the package [l1] is in, etc.
 
 {2 The units}
@@ -472,21 +472,21 @@ root>/doc/odoc-assets/].
 {2 The [--parent-id] arguments}
 
 Interface and implementation units have as parent id the root of the library
-tree they belong to: with "canonical" roots, [<pkgname>/lib/<libname>].
+tree they belong to: with "canonical" roots, [<pkgname>/<libname>].
 
 Page units that are found in [<opam
 root>/doc/<pkgname>/odoc-pages/<relpath>/<name>.mld] have the parent id from
 their page tree, followed by [<relpath>]. So, with canonical roots,
-[<pkgname>/doc/<relpath>].
+[<pkgname>/<relpath>].
 
 Asset units that are found in [<opam
 root>/doc/<pkgname>/odoc-pages/<relpath>/<name>.<ext>] have the parent id from
 their page tree, followed by [<relpath>]. With canonical roots,
-[<pkgname>/doc/<relpath>].
+[<pkgname>/<relpath>].
 
 Asset units that are found in [<opam root>/doc/<pkgname>/odoc-assets/<filename>]
 have the parent id from their page tree, followed by [_asset/<filename>]
-[<p>/doc/_assets/<filename>].
+[<p>/_assets/<filename>].
 
 {2 The [--source-id] arguments}
 

doc/odoc.mld

@@ -1,8 +1,7 @@
-{0 [odoc]}
+@children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver
+@short_title [odoc]
 
-{@meta[
-  children: dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver
-]}
+{0 The [odoc] documentation generator}
 
 {b For a quick look at the [odoc] syntax, see the {{!cheatsheet}cheatsheet}!}
 

doc/odoc_for_authors.mld

@@ -500,6 +500,9 @@ There are three types of tags. Those with:
 - a single line of text (line tags), and 
 - a block of marked-up text (block tags).
 
+Some tags can only be used on specific contexts: specific items ([include]s,
+[module]s, ...) or pages.
+
 {3 Simple Tags}
 
 The three tags without data are hints to the HTML renderer to do with [include]s.
@@ -535,6 +538,8 @@ and other tags. Note that compared to ocamldoc, block tags do not extend to the
 end of the docstring. Instead, they are ended by a blank line, or a block that
 cannot be included in (a heading or another tag).
 
+{4 Signature tags}
+
 - [@deprecated <text>] - marks the element as deprecated. [text] should describe
 when the element was deprecated, what to use as a replacement, and possibly
 the reason for the deprecation.
@@ -555,6 +560,29 @@ 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.
 
+{4 Page tags}
+
+These tags are the only tags that can be used on pages.
+
+- [@children_order <order>] - defines the order, in the sidebar, of the content
+  of a directory. It can only be used on [index.mld] pages. [<order>] must be a
+  space-separated list of content. Pages are referred by filename, and modules
+  are prefixed with [module-]. Directories are suffixed with a [/]. Here is an
+  example:
+  {[
+    @children_order content module-Unit dir1/
+  ]}
+
+- [@toc_status <status>] determines the behaviour of the entry in the sidebar
+  and breadcrumbs. It can only be used on [index.mld] pages. [<status>] can be
+  either [open] or [hidden]. If it is [open], the content of the directory will
+  always be displayed in the sidebar. If it is [hidden], it will be [opened] but
+  the directory entry, in the sidebar and breadcrumbs, will not be clickable.
+
+- [@order_category <category name>] helps defining the order of children for
+  pages unordered by the [@children_order] tag. Those unordered content will be
+  ordered by the lexicoraphic order on the category name.
+
 {2:math Mathematics}
 
 [odoc] 2.2 introduced new markup for maths, available both for inline and block