More fields in `@doc-json`

[dlesbre]

As mentioned in the discuss.ocaml post, I would appreciate a few extra fields in the generated JSON files to make integrating them in my website easier. jonludlam suggested I open an issue for these here as well:

• A title field with the page title (currently obtainable from breadcrumbs[-1].name
• A package field with the name of the current package (currently can be obtained from the path of the generated doc)
• A version field with the version of the current package (I'm building versioned docs). Currently I can only obtain this through git ref names.
• An objects fields with the list and type (val, module, type, module type...) of all objects defined in the current file
• A sherlodoc field indicating whether or not sherlodoc was present (and if so, the relative path from the current file to the db.js file).

[AllanBlanchard]

I don't know if it is entirely related, but this news:

https://tarides.com/blog/2024-02-28-two-major-improvements-in-odoc-introducing-search-engine-integration/

Suggests that the DB exists in Json, would it be possible to get it? The main problem with the db.js files is that if you have several packages in your project, the search engine does not merge all packages at top-level.

[jonludlam]

So, coming back to this, I think we can address a few of these for the v3.0 release, mostly because a lot of these were tricky prior to the existence of odoc_driver.

• Title is easy enough
• Package and Version - odoc itself doesn't know anything about these, but odoc_driver certainly does.
• objects - I'm not sure what this will be used for? And by "current file" - do you mean the HTML file (so not including submodes), or the odocl file (ie, top-level module and all submodules).

An alternative to putting all of these fields into the existing json output files, is that we coud output in the json the path to the top-level module. Unless you've got a very unusual layout (e.g. in the monorepo driver), this would be the 'package root', where we could put a package metadata file owned by odoc_driver. This could contain the sherlodoc db path, the name and version of the package, a reference to the sidebar json file, and potentially the json index with all of the 'contents' of the entire package. Would this work for you?

[AllanBlanchard]

where we could put a package metadata file owned by odoc_driver.

What would be the advantage with respect to having the very same information in the JSON? Having two files means that we have to parse two different files for extracting information (potentially with different formats?).

This could contain the sherlodoc db path.

Would the DB still be a JS file?

[panglesd]

odoc is responsible for generating the html/json files, but it has no notion of package. This is because it is used in many contexts: ocaml.org where we have package with multiple versions, opam-installed packages, monorepos including some without the notion of package, ...
So, each driver is responsible for defining the hierarchy according to the situation. odoc-driver in "opam mode" does internally have a notion of package.
So, only the driver can know the "package name".

(in any case, one file is metadata for a set of pages, while the other is metadata for a single page! So doesn't it make sense to have separated files?)

potentially with different formats?

both are in json!

Would the DB still be a JS file?

Currently, the driver only generate a JS file as odoc-driver does not provide support for server-side search out of the box.
However, you have several options:

• Modify change the driver to use `marshall here. This won't give your support for server-side search but the sherlodoc db files will be generated.
• Call sherlodoc directly to generate the db files. This gives you more freedom on what you want to index (maybe, if you want server-side search, you want to search in all packages?)

[panglesd]

@dlesbre

A title field with the page title (currently obtainable from breadcrumbs[-1].name)

What do you mean with "page title"?
Not every page contains a title. For instance, pages generated for modules do not have one! See this page for instance.

So, we would need to define a new notion just to put in in the field... I think it makes more sense to build your own idea of a title from the breadcrumbs!

[dlesbre]

For modules, I've used "module Name" as a page title (as is done in the default odoc generated pages by dune build @doc.

I generally think its good practice for webpages to have a clearly visible header (i.e. what is on this page?) and I feel the look of ocaml.org is a bit lacking in that regard.

[panglesd]

My bad, for some reason I was confused by the fact that ocaml.org does not show the header, and a testing error on my side.
And why does ocaml.org not include the header? Because it is not included in the json output!

I'll open a PR shortly with that. Thanks for your report!