Uniform treatment of sidebar #1251

panglesd · 2024-11-19T17:37:55Z

This PR is a change in how we handle the sidebar.

The current status is that we give the sidebar the modules and the pages separately. This is good because it allows them to be rendered separately which can be readable, but this is bad because:

It gives less flexibility in the sidebar/hierarchy (for instance in a monorepo we might want to hierarchize the modules) while letting it be quite uniform in the canonical case.
The sidebar and the breadcrumbs do not correspond
There are conflicts whenever the library roots are included in the pages roots
This does not handle implementations!

This PR changes the sidebar so that it is generated from the hierarchy of both modules, pages, sources, ...
The good things are above. The bad things are:

It is a bit harder to make it look good.
The children_order is more important (to have the libraries at the end).

Here is a preview for such a sidebar for ppxlib.

(It seems to me that we will need to add the @toc-expand tags)

I still need to clean up the history but the code should be ok already, and the discussion can start!

jonludlam · 2024-11-21T14:51:02Z

Thanks for this! It breaks sherlodoc though - do you have a branch of that that's compatible?

jonludlam · 2024-12-05T12:30:08Z

src/odoc/indexing.ml

@@ -55,136 +52,103 @@ let compile_to_json ~output ~occurrences files =
    false
  in
  Format.fprintf output "[";
-  let _ : bool =
+  let _first =


What's the reasoning behind only generating json fragments (and therefore having to pass around this 'first' thing) rather than generating a complete json object and simply outputting that?

I think the idea when we did that was not to have the full object in memory. Now, I think that we anyway have it in memory. I'll remove the first thing.

Done in 1e59b62!

jonludlam

This is looking good to me. We still need a better order for the sidebar when it's not specified in an index file. Other than that, I'm happy with this!

jonludlam · 2024-12-05T12:38:46Z

src/html/utils.ml

@@ -1,87 +1,3 @@
 (* Shared utility functions *)

 let optional_elt f ?a = function [] -> [] | l -> [ f ?a l ]


I think we can move this somewhere else now :-)

Done in f868577

jonludlam · 2024-12-05T12:41:33Z

src/model/frontmatter.ml

+   { Location_.value = `Paragraph [ { Location_.value = `Word "open"; _ } ]; _ };
+  ] ->
+      Result.Ok (Location_.at loc (Toc_status `Open))
+  | _ -> Error (Error.make "@toc_status can only take the 'open' value" loc)


Do you have any other values in mind that this might take?

The value I had in mind was hidden or private where it is both open and not rendered as a link.

Several changes: - Entries are now defined in the `odoc_index` library, - Entries can have new kinds (pages, source, ...) - Indexes have the form of "skeletons of entries", that can be folded. - Indexes can be created by odoc with the `odoc compile-index` command, and then consumed by sherlodoc. These changes come from: - ocaml/odoc#1228 - ocaml/odoc#1232 - ocaml/odoc#1233 - ocaml/odoc#1244 - ocaml/odoc#1250 - ocaml/odoc#1251

Document `@children_order`, `@order_category` and `@toc_status`.

This function was used by sherlodoc, it is not anymore.

jonludlam · 2024-12-10T09:47:33Z

Is @order_category ever going to be used by people documenting their packages, or is it more for the default index pages that are generated?

panglesd · 2024-12-10T09:58:28Z

There is a priori no need for @order_category for the people documenting their package, since they can already order the pages using children_order. Should I move the doc of this tag to the driver.mld page? Or make it explicit that it is for auto-generated pages?
In my opinion, it is fine to let people use it if they wish.

jonludlam · 2024-12-10T11:00:21Z

I'd rather make something like this internal only -- in the sense that it's not for 'ordinary' package authors -- for now; anything that people put in their actual repositories we have to support forever. We can document it in driver.mld but with some caveats that it might change in future.

Julow · 2024-12-10T12:38:05Z

doc/odoc.mld

@@ -1,8 +1,7 @@
-{0 [odoc]}
+@children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver


Shouldn't the cheatsheet be first ?

I though that the first thing was "how to build doc" before "how to write docs", which is why I put this page first, but I agree it is not ideal... I'll think about that a bit more.

Julow · 2024-12-10T12:39:47Z

src/document/sidebar.ml

@@ -2,72 +2,54 @@ open Odoc_utils
 open Types
 module Id = Odoc_model.Paths.Identifier

-type entry = Url.t option * Inline.one
+type entry = {
+  url : Url.t;


Why isn't url an option anymore ?

url is needed for computing breadcrumbs: You need that to orient yourself inside the provided sidebar, from the root to your current position.

Julow · 2024-12-10T12:47:06Z

src/odoc/bin/main.ml

+      "Wether to add a 'Home' breadcrumb to go up the root of the given \
+       sidebar."
+    in
+    Arg.(value & flag & info ~docv:"escape" ~doc [ "escape-breadcrumb" ])


I was confused when I read "escape" for the first time. What about "home-breadcrumb" or "root-breadcrumb" ?

Yes, escape is part of the "placeholder names" that need to be changed.

I'm happy with either of your proposition, but I think it would be even nicer to have a notion of "home below the sidebar root".

I went for home-breadcrumb

Julow · 2024-12-10T13:29:41Z

src/html/generator.ml

+              let href =
+                Some
+                  (Link.href ~config ~resolve:(Current current_url)
+                     (Odoc_document.Url.from_path parent))
+              in
+              [ { href; name = [ Html.txt "🏠" ]; kind = parent.kind } ])


This code can be shared with gen_breadcrumbs_no_sidebar

Thanks, I'll do that!

jonludlam · 2024-12-11T10:20:45Z

Thanks!

@jonludlam

CHANGES: ### Highlight - Hierarchical documentation (@jonludlam, @panglesd, @Julow) Pages can now be organized in a directory tree structure. Relative and absolute references are added: `{!./other_page.label}`, `{!//other_page}`. - Improved sidebar and breadcrumbs navigation (@panglesd, @gpetiot) The documentation pages and the libraries of the entire package are shown on the left sidebar. - Added support for images, videos, audio and other assets The syntax is `{image!/reference/to/asset}` or `{image:URL}` for images. The syntax for `{video...}` and `{audio...}` is the same. (@panglesd, @EmileTrotignon, ocaml/odoc#1170, ocaml/odoc#1171, ocaml/odoc#1184, ocaml/odoc#1185) - Search using Sherlodoc (@panglesd, @EmileTrotignon, @Julow) A new search bar that supports full-text and type-based search. ### Added - Experimental driver (@jonludlam, @panglesd) The driver builds the documentation for a collection of Opam packages using the newer Odoc features. It supports linking external packages to ocaml.org and markdown files. This is experimental and will break in the future. - Cross-package references (@panglesd, @Julow) Pages and modules from other packages can be referenced: `{!/otherpackage/page}`, `{!/otherpackage/Module.t}`. - Option to remap links to other packages to ocaml.org or other site. See the `--remap` option of the driver or the `--remap-file` option of `odoc html-generate`. (@jonludlam, ocaml/odoc#1189, ocaml/odoc#1248) - Option to compute occurrences of use of each identifiers The commands `aggregate-occurrences` and `count-occurrences` are added. (@panglesd, ocaml/odoc#976, ocaml/odoc#1076, ocaml/odoc#1206) - Added the `odoc classify` command (@jonludlam, ocaml/odoc#1121) Helps driver detecting which modules belong to which libraries. - Added `--suppress-warnings` to the CLI to remove warnings from a unit, even if they end up being raised in another unit through expansion (@jonludlam, ocaml/odoc#1260) - Add clock emoji before `@since` tag (@yawaramin, ocaml/odoc#1089) - 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, ocaml/odoc#1088) - Fix a big gap between the preamble and the content of a page (@EmileTrotignon, ocaml/odoc#1147) - Add a marshalled search index consumable by sherlodoc (@EmileTrotignon, @panglesd, ocaml/odoc#1084) - Allow referencing of polymorphic constructors in polymorphic variant type aliases (@panglesd, ocaml/odoc#1115) - Added a home icon in the breacrumbs (@panglesd, ocaml/odoc#1251) It can be disabled with a CLI option. - Add a frontmatter syntax for mld pages (@panglesd, ocaml/odoc#1187, ocaml/odoc#1193, ocaml/odoc#1243, ocaml/odoc#1246, ocaml/odoc#1251) Allows to specify the title of a page, the order of sub-pages and other behaviors in the sidebar. - Added `odoc-md` to process standalone Markdown pages (@jonludlam, ocaml/odoc#1234) ### Changed - The command line interface changed to support the new features. + Packages and libraries: `odoc link` must now be aware of packages and libraries with the `-L libname:path` and `-P pkgname:path` options. The module search path should still be passed with the `-I` option. The current package should be specified with `--current-package=pkgname`. + Hierarchy: `odoc compile` now outputs `.odoc` in the directory tree specified with `--output-dir=DIR` and the parent identifier must be specified with `--parent-id=PARENT`. The option `--source-parent-file` is removed. + Source code: Implementations are compiled with `compile-impl` instead of with `compile`. The options `--cmt=..` and `--source-name=..` are removed. Source code pages are generated with `html-generate-source`. + Assets: The commands `compile-asset`, `html-generate-asset` are added. The option `html-generate --asset` is removed. + Sidebar: The index is built using `compile-index`. The sidebar data is extracted from the index with `sidebar-generate` and passed to `html-generate --sidebar=..`. - The syntax for `@tag` is now delimited (@panglesd, ocaml/odoc#1239) A `@tag` can now be followed by a paragraph or other elements. - Updated colors for code fragments (@EmileTrotignon, ocaml/odoc#1023) - Fixed complexity of looking up `.odoc` files (@panglesd, ocaml/odoc#1075) - Normalize whitespaces in codespans (@gpetiot, ocaml/odoc#1085) A newline followed by any whitespaces is normalized as one space character. - Reduce size of `Odoc_html_frontend` when compiled to javascript (@EmileTrotignon, ocaml/odoc#1072) - Overhaul of module-type-of expansions and shadowing code (@jonludlam, ocaml/odoc#1081) - Output file paths and labels in the man and latex backends changed to avoid name clashes (@Julow, ocaml/odoc#1191) ### Fixed - Fix variant constructors being hidden if they contain hidden types (@jonludlam, ocaml/odoc#1105) - Fix rare assertion failure due to optional parameters (@jonludlam, ocaml/odoc#1272, issue ocaml/odoc#1001) - Fix resolution of module synopses in {!modules} lists that require --open (@jonludlam, ocaml/odoc#1104} - Fix top comment not being taken from includes often enough (@panglesd, ocaml/odoc#1117) - Fixed 404 links from search results (@panglesd, ocaml/odoc#1108) - Fixed title content not being picked up across pages when rendering references (ocaml/odoc#1116, @panglesd) - Fix wrong links to standalone comments in search results (ocaml/odoc#1118, @panglesd) - Remove duplicated or unwanted comments with inline includes (@Julow, ocaml/odoc#1133) - Fix bug where source rendering would cause odoc to fail completely if it encounters invalid syntax (@jonludlam ocaml/odoc#1208) - Add missing parentheses in 'val (let*) : ...' (@Julow, ocaml/odoc#1268) - Fix syntax highlighting not working for very large files (@jonludlam, @Julow, ocaml/odoc#1277)

@jonludlam

CHANGES: - Hierarchical documentation (@jonludlam, @panglesd, @Julow) Pages can now be organized in a directory tree structure. Relative and absolute references are added: `{!./other_page.label}`, `{!//other_page}`. - Improved sidebar and breadcrumbs navigation (@panglesd, @gpetiot) The documentation pages and the libraries of the entire package are shown on the left sidebar. - Added support for images, videos, audio and other assets The syntax is `{image!/reference/to/asset}` or `{image:URL}` for images. The syntax for `{video...}` and `{audio...}` is the same. (@panglesd, @EmileTrotignon, ocaml/odoc#1170, ocaml/odoc#1171, ocaml/odoc#1184, ocaml/odoc#1185) - Search using Sherlodoc (@panglesd, @EmileTrotignon, @Julow) A new search bar that supports full-text and type-based search. - Experimental driver (@jonludlam, @panglesd) The driver builds the documentation for a collection of Opam packages using the newer Odoc features. It supports linking external packages to ocaml.org and markdown files. This is experimental and will break in the future. - Cross-package references (@panglesd, @Julow) Pages and modules from other packages can be referenced: `{!/otherpackage/page}`, `{!/otherpackage/Module.t}`. - Option to remap links to other packages to ocaml.org or other site. See the `--remap` option of the driver or the `--remap-file` option of `odoc html-generate`. (@jonludlam, ocaml/odoc#1189, ocaml/odoc#1248) - Option to compute occurrences of use of each identifiers The commands `aggregate-occurrences` and `count-occurrences` are added. (@panglesd, ocaml/odoc#976, ocaml/odoc#1076, ocaml/odoc#1206) - Added the `odoc classify` command (@jonludlam, ocaml/odoc#1121) Helps driver detecting which modules belong to which libraries. - Added `--suppress-warnings` to the CLI to remove warnings from a unit, even if they end up being raised in another unit through expansion (@jonludlam, ocaml/odoc#1260) - Add clock emoji before `@since` tag (@yawaramin, ocaml/odoc#1089) - 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, ocaml/odoc#1088) - Fix a big gap between the preamble and the content of a page (@EmileTrotignon, ocaml/odoc#1147) - Add a marshalled search index consumable by sherlodoc (@EmileTrotignon, @panglesd, ocaml/odoc#1084) - Allow referencing of polymorphic constructors in polymorphic variant type aliases (@panglesd, ocaml/odoc#1115) - Added a home icon in the breacrumbs (@panglesd, ocaml/odoc#1251) It can be disabled with a CLI option. - Add a frontmatter syntax for mld pages (@panglesd, ocaml/odoc#1187, ocaml/odoc#1193, ocaml/odoc#1243, ocaml/odoc#1246, ocaml/odoc#1251) Allows to specify the title of a page, the order of sub-pages and other behaviors in the sidebar. - Added `odoc-md` to process standalone Markdown pages (@jonludlam, ocaml/odoc#1234) - The command line interface changed to support the new features. + Packages and libraries: `odoc link` must now be aware of packages and libraries with the `-L libname:path` and `-P pkgname:path` options. The module search path should still be passed with the `-I` option. The current package should be specified with `--current-package=pkgname`. + Hierarchy: `odoc compile` now outputs `.odoc` in the directory tree specified with `--output-dir=DIR` and the parent identifier must be specified with `--parent-id=PARENT`. The option `--source-parent-file` is removed. + Source code: Implementations are compiled with `compile-impl` instead of with `compile`. The options `--cmt=..` and `--source-name=..` are removed. Source code pages are generated with `html-generate-source`. + Assets: The commands `compile-asset`, `html-generate-asset` are added. The option `html-generate --asset` is removed. + Sidebar: The index is built using `compile-index`. The sidebar data is extracted from the index with `sidebar-generate` and passed to `html-generate --sidebar=..`. - The syntax for `@tag` is now delimited (@panglesd, ocaml/odoc#1239) A `@tag` can now be followed by a paragraph or other elements. - Updated colors for code fragments (@EmileTrotignon, ocaml/odoc#1023) - Fixed complexity of looking up `.odoc` files (@panglesd, ocaml/odoc#1075) - Normalize whitespaces in codespans (@gpetiot, ocaml/odoc#1085) A newline followed by any whitespaces is normalized as one space character. - Reduce size of `Odoc_html_frontend` when compiled to javascript (@EmileTrotignon, ocaml/odoc#1072) - Overhaul of module-type-of expansions and shadowing code (@jonludlam, ocaml/odoc#1081) - Output file paths and labels in the man and latex backends changed to avoid name clashes (@Julow, ocaml/odoc#1191) - Fix variant constructors being hidden if they contain hidden types (@jonludlam, ocaml/odoc#1105) - Fix rare assertion failure due to optional parameters (@jonludlam, ocaml/odoc#1272, issue ocaml/odoc#1001) - Fix resolution of module synopses in {!modules} lists that require --open (@jonludlam, ocaml/odoc#1104} - Fix top comment not being taken from includes often enough (@panglesd, ocaml/odoc#1117) - Fixed 404 links from search results (@panglesd, ocaml/odoc#1108) - Fixed title content not being picked up across pages when rendering references (ocaml/odoc#1116, @panglesd) - Fix wrong links to standalone comments in search results (ocaml/odoc#1118, @panglesd) - Remove duplicated or unwanted comments with inline includes (@Julow, ocaml/odoc#1133) - Fix bug where source rendering would cause odoc to fail completely if it encounters invalid syntax (@jonludlam ocaml/odoc#1208) - Add missing parentheses in 'val (let*) : ...' (@Julow, ocaml/odoc#1268) - Fix syntax highlighting not working for very large files (@jonludlam, @Julow, ocaml/odoc#1277)

panglesd force-pushed the root-in-sidebar-really branch from aa1bc95 to 15defae Compare November 21, 2024 16:41

gpetiot mentioned this pull request Nov 21, 2024

odoc_index: Replace -P/-L with --root arguments #1247

Closed

panglesd force-pushed the root-in-sidebar-really branch 3 times, most recently from a00a1ab to e2a73b3 Compare November 27, 2024 17:13

jonludlam reviewed Dec 5, 2024

View reviewed changes

panglesd force-pushed the root-in-sidebar-really branch 3 times, most recently from f5acc73 to 022058e Compare December 6, 2024 07:28

panglesd mentioned this pull request Dec 6, 2024

Dedicated sidebar file #1250

Merged

panglesd force-pushed the root-in-sidebar-really branch 6 times, most recently from 018c6e0 to 3656a16 Compare December 6, 2024 15:49

panglesd added 12 commits December 6, 2024 17:43

WIP

5acab30

WIP 2

a3e3aad

small improvements

0f9ae22

Rename file

99abfa2

Create a separate module for intermediate index

6f5cd16

Allow to order modules

d743543

Sidebar: Use a better name when no zero title are there

4f0b909

Remove resolver logic to return all pages

416b465

Keep --root groups

7f23b64

Use computed index to compute json

7294fc4

Fix adding container pages in indexes

db9afcb

Index: handle roots even when they are included in each others

0a0f1d7

compatibility

63f50e8

panglesd force-pushed the root-in-sidebar-really branch from 3656a16 to 417d4b4 Compare December 6, 2024 16:44

panglesd added a commit to panglesd/odoc that referenced this pull request Dec 9, 2024

Changelog entry for ocaml#1251

7f77f1e

panglesd mentioned this pull request Dec 9, 2024

Odoc compatibility art-w/sherlodoc#46

Open

panglesd added a commit to panglesd/odoc that referenced this pull request Dec 9, 2024

Changelog entry for ocaml#1251

4ea9198

panglesd force-pushed the root-in-sidebar-really branch from 6d3c2a6 to a3a5cdf Compare December 9, 2024 17:36

panglesd added 7 commits December 9, 2024 20:01

Add a 'Home' link to breadcrumbs when no sidebar is given

6825e3c

Fix default order of children

6779665

Changelog entry for ocaml#1251

a4b69c2

Doc: page tags

5103c6b

Document `@children_order`, `@order_category` and `@toc_status`.

Doc: update canonical roots to the doclibless hierarchy

ccf3f01

Index: add support for extension constructors

3b53164

Remove now unused handle_file function

9cf80ab

This function was used by sherlodoc, it is not anymore.

panglesd force-pushed the root-in-sidebar-really branch from a3a5cdf to 9cf80ab Compare December 9, 2024 19:02

Doc: explicitly make @order_category a driver-only tag

5a15d21

Julow reviewed Dec 10, 2024

View reviewed changes

jonludlam pushed a commit to jonludlam/odoc that referenced this pull request Dec 10, 2024

Changelog entry for ocaml#1251

b53bfd0

panglesd added 2 commits December 11, 2024 10:01

Breadcrumbs: factor home breadcrumb

4a6d2bd

Breadcrumb: rename escape-breadcrumb to home-breadcrumb

dea50a4

jonludlam merged commit 7fa3d8b into ocaml:master Dec 11, 2024
13 checks passed

jonludlam pushed a commit that referenced this pull request Dec 11, 2024

Changelog entry for #1251

44c3fab

Julow mentioned this pull request Dec 11, 2024

Compatibility with changed index and kind types panglesd/sherlodoc#2

Closed

jonludlam mentioned this pull request Jan 23, 2025

[new release] odoc (5 packages) (3.0.0~beta1) ocaml/opam-repository#27309

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uniform treatment of sidebar #1251

Uniform treatment of sidebar #1251

panglesd commented Nov 19, 2024

jonludlam commented Nov 21, 2024

jonludlam Dec 5, 2024

panglesd Dec 5, 2024

panglesd Dec 6, 2024

jonludlam left a comment

jonludlam Dec 5, 2024

panglesd Dec 6, 2024

jonludlam Dec 5, 2024

panglesd Dec 5, 2024

jonludlam commented Dec 10, 2024

panglesd commented Dec 10, 2024

jonludlam commented Dec 10, 2024

Julow Dec 10, 2024

panglesd Dec 10, 2024

Julow Dec 10, 2024

panglesd Dec 10, 2024

Julow Dec 10, 2024

panglesd Dec 10, 2024 •

edited

Loading

panglesd Dec 11, 2024

Julow Dec 10, 2024

panglesd Dec 10, 2024

panglesd Dec 11, 2024

jonludlam commented Dec 11, 2024

		@@ -1,87 +1,3 @@
		(* Shared utility functions *)

		let optional_elt f ?a = function [] -> [] \| l -> [ f ?a l ]

		@@ -1,8 +1,7 @@
		{0 [odoc]}
		@children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver

Uniform treatment of sidebar #1251

Uniform treatment of sidebar #1251

Conversation

panglesd commented Nov 19, 2024

jonludlam commented Nov 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonludlam left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonludlam commented Dec 10, 2024

panglesd commented Dec 10, 2024

jonludlam commented Dec 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

panglesd Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonludlam commented Dec 11, 2024

panglesd Dec 10, 2024 •

edited

Loading