feat: use output from new doc-ci with odoc 3 features in the package documentation area #3124

panglesd · 2025-05-21T11:00:51Z

Replaces #3123, but PR is on main.

This PR uses the output from the new doc-ci @jonludlam has been working on. The docs are built with odoc 3, benefiting from several features, some of them that were previously "emulated" on this repo (such as a global sidebar).

This currently implements:

A global sidebar as computed by odoc 3
Better breadcrumbs
Source code pages
Redirections for url changes

This PR is not yet complete, however all pushed commits can already be reviewed, so I think it was already worth opening.
I tried to make the commits as atomic as possible to ease the review, which can then be made "commit by commit". All commits compile, although they may fail at runtime (eg due to wrong format for deserializing).

I'll post updates and warn when I consider the PR complete!

sabine · 2025-05-26T10:21:28Z

I converted this to a draft, but feel free to ping me any time when it makes sense to test this. I will put this on https://staging.ocaml.org, and hook it up with the staging docs-ci.

yawaramin · 2025-06-03T00:31:08Z

Does this make #1963 obsolete?

jonludlam · 2025-06-03T08:53:01Z

Does this make #1963 obsolete?

Yes.

panglesd · 2025-06-03T13:27:28Z

@sabine @jonludlam This is ready for testing on staging!

(I don't know what makes the "deployability" CI fail but I don't think it's related)

… documentation area #3124 (e9d2ab9)

sabine · 2025-06-06T07:44:17Z

Deploying on staging.ocaml.org (https://deploy.ci.ocaml.org/job/2025-06-06/074257-ocluster-build-384752)

jonludlam · 2025-06-09T13:44:36Z

The source rendering needs some CSS love:

panglesd · 2025-06-10T08:03:29Z

Did you take the screenshot from staging.ocaml.org? Here is how the same page looks for me:

Light mode:

Dark mode:

I'll try to reproduce with different browser and settings, but if you have any hint, I'll take them.

panglesd · 2025-06-10T18:06:22Z

Ok, testing on chromium yields the same CSS problem...

… documentation area #3124 (e6df934)

sabine · 2025-06-10T20:15:25Z

Deploying updated PR to staging.

… documentation area #3124 ( b30d4c1 )

… documentation area #3124 (40127b5)

… documentation area #3124 (52d1860)

sabine · 2025-07-01T09:17:49Z

src/ocamlorg_web/lib/handler.ml

+              | Some "module" -> Module
+              | (Some ("page" | "leaf-page") | None)
+                when String.starts_with ~prefix:"Library " sidebar.node.content
+                ->
+                  Library
+              | Some ("page" | "leaf-page") -> Page
+              | Some "module-type" -> Module_type
+              | Some "parameter" -> Parameter
+              | Some "class" -> Class
+              | Some "class-type" -> Class_type
+              | Some "file" -> File
+              | Some "source" -> Source
+              | None -> Page


makes sense to do this decoding in the Sidebar module in ocamlorg_package/, instead of here

Co-authored-by: Jon Ludlam <[email protected]>

It was added in ocaml/odoc#1314 and needs not be ignored Co-authored-by: Jon Ludlam <[email protected]>

Co-authored-by: Jon Ludlam <[email protected]>

From https://alpinejs.dev/directives/cloak : > Sometimes, when you're using AlpineJS for a part of your template, there is a > "blip" where you might see your uninitialized template after the page loads, > but before Alpine loads. > > `x-cloak` addresses this scenario by hiding the element it's attached to until > Alpine is fully loaded on the page. > > For `x-cloak` to work however, you must add the following CSS to the page. > > ``` > [x-cloak] { display: none !important; } > ```

Since odoc 3, and the replacement of voodoo by odoc_driver as the odoc driver, the layout for docs has changed. Since we do not want to break previously existing links, we redirect the old layout to the new one.

Documentation assets are not present as json files. Therefore, if we do not find a .json target, we try to load it as an asset. This is not ideal: assets always require two requests to the documentation server. 404 pages also trigger two requests...

Odoc 3's search has already a leading `/`.

`old_path` and `new_path` do not include the prefix, which makes the detection of redirection harder. Previously, the url `/p/odoc/3.0.0/doc/odoc.odoc/Odoc_odoc/Sidebar/index.html` would trigger the rewriting: `doc/Odoc_odoc/Sidebar/index.html` -> `doc/odoc.odoc/Odoc_odoc/Sidebar/index.html` which is a bug. Adding a / in the rewriting rules solves it

shonfeder · 2025-07-02T16:41:43Z

Hello! Congrats on this work, @panglesd!

@sabine, just FYI, I will be taking over responsibility for helping ensure this lands.

If any additional work is needed here, I'll respond, and if not I may ping with followups until it is in :)

Thanks!

jonludlam · 2025-07-03T10:35:49Z

Can we please not merge this PR for a few days - I just need to fiddle with the storage on the new server and I'd rather not do that when it's being used! I'll update when the changes have been done.

panglesd mentioned this pull request May 21, 2025

Documentation: use output from new doc-ci with odoc 3 features #3123

Closed

4 tasks

panglesd force-pushed the odoc-3.0-reworked branch 3 times, most recently from 9a5f418 to 62d32b9 Compare May 21, 2025 13:04

sabine marked this pull request as draft May 26, 2025 10:20

sabine changed the title ~~Documentation: use output from new doc-ci with odoc 3 features~~ Package Documentation Area: use output from new doc-ci with odoc 3 features May 26, 2025

sabine changed the title ~~Package Documentation Area: use output from new doc-ci with odoc 3 features~~ feat: use output from new doc-ci with odoc 3 features in the package documentation area May 26, 2025

panglesd force-pushed the odoc-3.0-reworked branch from 52920b2 to 3f494dd Compare June 3, 2025 09:41

sabine added a commit that referenced this pull request Jun 6, 2025

feat: use output from new doc-ci with odoc 3 features in the package…

d2674ce

… documentation area #3124 (e9d2ab9)

sabine added a commit that referenced this pull request Jun 10, 2025

feat: use output from new doc-ci with odoc 3 features in the package…

098340b

… documentation area #3124 (e6df934)

panglesd force-pushed the odoc-3.0-reworked branch from 6c9e7de to b30d4c1 Compare June 11, 2025 06:54

panglesd marked this pull request as ready for review June 11, 2025 07:33

sabine added a commit that referenced this pull request Jun 11, 2025

feat: use output from new doc-ci with odoc 3 features in the package…

15980a1

… documentation area #3124 ( b30d4c1 )

sabine added a commit that referenced this pull request Jun 11, 2025

feat: use output from new doc-ci with odoc 3 features in the package…

75fe34e

… documentation area #3124 (40127b5)

sabine added a commit that referenced this pull request Jun 20, 2025

feat: use output from new doc-ci with odoc 3 features in the package…

34a86ef

… documentation area #3124 (52d1860)

sabine reviewed Jul 1, 2025

View reviewed changes

panglesd and others added 5 commits July 1, 2025 14:10

Get docs from new docs CI

73dd76f

Co-authored-by: Jon Ludlam <[email protected]>

Docs: Update to new odoc3 json format

0a23bab

Co-authored-by: Jon Ludlam <[email protected]>

Docs: use new status.json from odoc 3

44258e2

Co-authored-by: Jon Ludlam <[email protected]>

Docs: use header field

6f08841

It was added in ocaml/odoc#1314 and needs not be ignored Co-authored-by: Jon Ludlam <[email protected]>

Docs: fix search script location change with odoc_driver

0f63921

Co-authored-by: Jon Ludlam <[email protected]>

panglesd and others added 22 commits July 1, 2025 14:10

rename library_path to path: pages also have/are in breadcrumbs

ba702ec

Co-authored-by: Jon Ludlam <[email protected]>

Docs breadcrumbs: use the one computed by odoc without processing

69b5f88

Co-authored-by: Jon Ludlam <[email protected]>

Add dependency on ppx_deriving_yojson

bd82131

Add source pages to docs

7d685f0

Render html in breadcrumbs

4f61be6

Add style for rendered source code

7a857ce

Handle redirection

6ec1785

Since odoc 3, and the replacement of voodoo by odoc_driver as the odoc driver, the layout for docs has changed. Since we do not want to break previously existing links, we redirect the old layout to the new one.

Sidebar: open sub-toc when clicking on a page from the sidebar

e9587c5

Doc: handle asset loading

d731d82

Documentation assets are not present as json files. Therefore, if we do not find a .json target, we try to load it as an asset. This is not ideal: assets always require two requests to the documentation server. 404 pages also trigger two requests...

Fix package files' links

678f4ee

Fix package files appearing in global toc

69024bb

Fix theme for source rendering

293b3af

Revert keeping the sidebar on new page loading

43a299b

Finally implement avoid reloading sidebar

187ec81

Docs: Improve source code target highlighting

22fbf20

Improve css of source rendering line numbers

9a0ebe3

Improve links to source style

b8a5407

Docs: only show right sidebar when it exists

983f9cb

Improve error handling for status.json

1a48322

Fix enter on search result

a2fd81b

Odoc 3's search has already a leading `/`.

panglesd force-pushed the odoc-3.0-reworked branch from 41a4b4c to 9ff58c1 Compare July 1, 2025 12:15

panglesd added 2 commits July 1, 2025 16:41

Put documentation-related code in a documentation file

587c891

Consider non-html files as assets

677730a

panglesd mentioned this pull request Jul 1, 2025

odoc_driver_voodoo and org files ocaml/odoc#1359

Open

panglesd added 2 commits July 1, 2025 17:29

Turn sidebar into Navmap earlier

69dec17

Increment cache version and update comments around it

3c2f4ac

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: use output from new doc-ci with odoc 3 features in the package documentation area #3124

feat: use output from new doc-ci with odoc 3 features in the package documentation area #3124

Uh oh!

panglesd commented May 21, 2025 •

edited

Loading

Uh oh!

sabine commented May 26, 2025

Uh oh!

yawaramin commented Jun 3, 2025

Uh oh!

jonludlam commented Jun 3, 2025

Uh oh!

panglesd commented Jun 3, 2025

Uh oh!

sabine commented Jun 6, 2025

Uh oh!

jonludlam commented Jun 9, 2025

Uh oh!

panglesd commented Jun 10, 2025

Uh oh!

panglesd commented Jun 10, 2025

Uh oh!

sabine commented Jun 10, 2025

Uh oh!

sabine Jul 1, 2025

Uh oh!

shonfeder commented Jul 2, 2025 •

edited

Loading

Uh oh!

jonludlam commented Jul 3, 2025

Uh oh!

Uh oh!

feat: use output from new doc-ci with odoc 3 features in the package documentation area #3124

Are you sure you want to change the base?

feat: use output from new doc-ci with odoc 3 features in the package documentation area #3124

Uh oh!

Conversation

panglesd commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sabine commented May 26, 2025

Uh oh!

yawaramin commented Jun 3, 2025

Uh oh!

jonludlam commented Jun 3, 2025

Uh oh!

panglesd commented Jun 3, 2025

Uh oh!

sabine commented Jun 6, 2025

Uh oh!

jonludlam commented Jun 9, 2025

Uh oh!

panglesd commented Jun 10, 2025

Uh oh!

panglesd commented Jun 10, 2025

Uh oh!

sabine commented Jun 10, 2025

Uh oh!

sabine Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

shonfeder commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonludlam commented Jul 3, 2025

Uh oh!

Uh oh!

panglesd commented May 21, 2025 •

edited

Loading

shonfeder commented Jul 2, 2025 •

edited

Loading