Support inlining expansions in their parent's page

[lpw25]

Sometimes people have small sub-modules and they would prefer to get something like:

  module Foo : sig
  
    type t
    
    val x : t
    
  end

in their docs instead of:

  module Foo : sig ... end

and a separate page for Foo.

It would be nice to allow users to annotate modules with some kind of tag to indicate that they would like this behaviour. It would require support in the model since links that used to go to the separate Foo page would now need to go to its parent page.

[lpw25]

I thought we already had an issue for this, but I couldn't find it. I also think this feature request is pretty low priority at the moment.

[ulrikstrid]

Semi-related: https://github.com/ocaml/odoc/issues/323

Also, I really want this 😄

[Drup]

I was slightly confused so I checked: It's already supported everywhere .... except there are no annotations for this in the syntax, unlike include. The models and everything down already does the right thing. In fact, both the latex and man output automatically unfold submodules, and the links are still correct in latex.

[lpw25]

I don't see how the links can be correct. You need to add a new form to the path syntax to represent "project submodule 'Foo' that is in the same page as its parent" and then resolving has to detect an annotation on the definitions and decide to use that projection rather than the ordinary one. Otherwise it will try to link to a non-existent page for the submodule.

[lpw25]

To be clear, this is fine in latex because there is only one possible projection in latex. In the html there will be two possible projections and resolution needs to produce the correct one.

[ulrikstrid]

Related to this I would like it if we can expand module type in the file. My usecase is that I have a "API" module type that then different modules implement. So I would like to showcase the API in the main module so that it's immediately obvious instead of clicking into one of the implementations.

[jonludlam]

Right - we'll also need to be careful with anchors as doing it naively will cause name clashes.

[jonludlam]

I'll rename this so it applies to all expansions rather than just modules.

[dmbaturin]

I also would like to see this implemented.

[dbuenzli]

I think this is a pretty bad idea and should not be implemented. I'll just repeat here what I said in that discussion on discuss.

I'm not saying you won't be able to find examples where the feature makes sense.

The problem is that everyone will have a different definition of what is small, or some will have the impression that it's always better to inline everything regardless of the size of the module. So in aggregate docsets like those generated by odig for your opam switches, you get an unpredictable structure for end users (starting with the hackability of URLs).

Now someone of course will say oh but you should be able to override it on the cli of odoc but that's not good either because the way you write your docs does depend on the structure of the output, so you don't want to be betrayed by it later.

[dmbaturin]

Do you think it would be feasible to implement it as a documentation comment directive?

[dbuenzli]

Do you think it would be feasible to implement it as a documentation comment directive?

I don't see how this solves the problems I mentioned, namely that 1) Everyone is going to have it's own notion of what is small 2) If you allow to force ignoring the directive then you betray what the author had in mind.

If you hadn't allowed it in the first place the author would maybe have worked around the inability to inline in pathological cases in a creative way (e.g. by authoring a list with direct links).

Another argument against it is that 3) What is small may become big later when the code evolves (or a new maintainer has a different notion of what in small). Then the author or new maintainer changes the inlining desire and you just broke external links into the docs.

It is important for odoc to enforce a regular structure on what OCaml documentation should be and look like. Both for end users so that they don't have to learn new conventions each time they peruse a new package and for authors so that they can have reasonable expectations on what it will look like in all the contexts (odig, project website, docs.ocaml.org) as this does influence the way you design your documents and linking structure.

I think it already became too flexible, if you compare odig/dune generated docsets with what is currently on v3.ocaml.org there is already one pretty bad difference which as an author I dislike. Namely it is wrong to have "in this package" before "on this page", on a laptop screen you don't see "on this page". Yet that's what you are most interested in when you get on a page since it gives you its signposts, but in most cases this will end up burried behind scrolling which is really bad.

I always take a lot of care to design my heading structure so that a good toc is generated for efficient access to elements on the page. And that work is totally destroyed by this rendering on v3.ocaml.org (also for some reason the page is missing the title and preamble, see here for a good rendering).

[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.

[dmbaturin]

@github-actions No, bot, just because no one is actively working on it now, the issue doesn't become less relevant. ;)