{!indexlist} not supported and/or alternative unspecified

[jonludlam]

[dbuenzli]

This is also tracked and discussed in #52.

I'm don't know if the directive itself has to be supported (except maybe to link on the index page) but it would be nice to find a scheme to be able to generate an index page for a set of odoc(l)? files. They allow to quickly glance the names that exist which can be useful for design and provide a poor but effective man's search via the browser's in-page search.

For example in odig we could have an index page per package + an index page for all packages. As I mentioned in #52. I don't think it's necessary to have separate indexes for types and values like ocamldoc does.

[jonludlam]

Next step: come up with a suggestion for what we should do!

[dbuenzli]

Next step: come up with a suggestion for what we should do!

Here's a (maybe too) simple suggestion. Add an odoc mld-index [ -o MLD] ODOC... command that simply spits out an .mld file with the index for the given odoc files.

[Julow]

{!indexlist} is generating links to the indexes and not the indexes themselves. This doesn't apply to Odoc and is replaced by --parent/--child and the sidebar. It's currently the driver's responsibility to generate indexes, Odoc wouldn't have more informations than the driver here. If we wanted to make generating the indexes easier, my suggestion would be to add a {!children} markup that purpose (similar to what {!modules: ...} should do).

[dbuenzli]

@Julow I'm afraid I can't make sense of what you are saying. In any case there is no provision to generate indexes of values, types and modules in odoc at the moment and I think one should be added.

[Julow]

Indeed there is no way to generate indexes like ocamldoc does. My comment above is about listing compilations units, which doesn't make sense.

The data contained into indexes would be useful for other purposes so I suggest adding a command to extract that information from odoc files: odoc index [-o SEXP] ODOC.... This can be useful to build complex features outside of odoc, like search or to build custom indexes (eg. when building the documentation of several packages). That is not incompatible with mld-index, which would be useful when building the documentation for a single package.

[avsm]

odoc dev meeting notes:

There is some confusion among the odoc developers (!) what indexlist precisely does. For reference, the ocamldoc manual says:

{!indexlist} | insert a table of links to the various indexes (types, values, modules, ...). Used in HTML only.

We need to figure out the way forward for two distinct features:

• how to generate toplevel modules list (something like {!modules} but without the manual list). @drup investigating what this is (in Batteries/Lwt?)
• how to generate indexes of available types/values/modules

We don't need to stick to the ocamldoc syntax for this, if something newer works better. This is because the ocamldoc syntax is marked in the manual as for the HTML backend only, so it's a backend-specific bit of syntax that could be adapted to fit odoc better.

[Drup]

• how to generate toplevel modules list (something like {!modules} but without the manual list). @Drup investigating what this is (in Batteries/Lwt?)

I was convinced it existed (and apparently I was not the only one), but neither @Octachron nor I can find it again, so I guess we had a collective hallucination.

how to generate indexes of available types/values/modules

During the dev meeting, we decided to follow @Julow 's plan: 1) discontinue support of the indexlist command itself 2) Eventually (after 2.0) support automatic generation of indexes with an auxiliary command, which will be linked from the sidebar.

[dbuenzli]

I'm still missing this quite a bit. Index pages are very useful to check for API design consistency (and of course for poor man's identifier search). To give a bit more ideas to whoever takes on this here's a very old comment about how I think the index should be structured.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.