Allow level-1 headings in mli files

[bluddy]

I can't get any proper documentation output on 4.06.1. This happens even after pinning to dune master, which has an issue which seemed to be similar to what I'm seeing.

Steps to reproduce:

1. Install 4.06.1 and dune/jbuilder.
2. Clone https://github.com/rizo/order.
3. Run jbuilder build @doc.
4. Open _build/default/_doc/_html/index.html
5. Click on the order package.
6. Click on the Order module.
7. Click on the Ordered interface. You should get a 404 -- this resource wasn't created.

Running on odoc itself produces similar issues -- nothing is created inside the odoc package.

(To try out pinning to dune master, you currently have to use dune as the package name and prompt opam to create it, or both dune and jbuilder will not be available.)

[bobbypriam]

I can reproduce this using the steps given above. Some pages are not generated.

dune ver.	odoc ver.	docs working?
1.0+beta20	1.2.0	Yes
dev	1.2.0	Yes
1.0+beta20	dev	No
dev	dev	No

FWIW, there were several warnings emitted when using odoc.dev:

$ jbuilder build @doc
        odoc _doc/_odoc/lib/order/Order.odoc
File "src/Order.mli", line 322, character 53 to line 323, character 12:
line break is not allowed in '[...]' (code)
File "src/Order.mli", line 364, character 61 to line 365, character 31:
line break is not allowed in '[...]' (code)
File "src/Order.mli", line 389, character 75 to line 390, character 8:
line break is not allowed in '[...]' (code)

But even after fixing those errors (deleting the line breaks) the docs are still not generated properly, now without warnings or errors.

[bluddy]

Looks like the breaking commit was here, which is consistent with the dune bug I think. This commit stops @rizo's order library from building proper documentation, for example. It's strange that the new dune version doesn't fix it. Anyway, hopefully this information is helpful.

[rizo]

@bluddy thanks for reporting this and sorry for the delay.

This is still related to the {1 ...} error. The mentioned issue in dune has nothing to do with this because it's odoc that has this restriction. The submitted fix in dune simply stops using title-level headings avoiding the restriction.

I've also "fixed" this now in the order library by pushing a change that doesn't use {1 ...}.

@aantron I think we should relax this restriction somehow.

[dbuenzli]

@aantron I think we should relax this restriction somehow.

See here for a rationale.

[aantron]

And here for a counterargument, I guess we should move that discussion here.

The current behavior is supposed to be to clamp headings to levels [2-4] in mlis, [1-4] for the first title in a mld, issue a warning, and continue parsing. Obviously, there is some kind of bug with that, but I don't have time to take a look immediately. odoc shouldn't be stopping with a fatal error. We shared some links in chat about the code that might be at fault.

[aantron]

@Octachron also has a note about the history of {1 in ocamldoc here.

I'd also like to add that in case we support LaTeX output, [2-4] map onto \section, \subsection, and \subsubsection quite nicely.

[dbuenzli]

As @Octachron mentioned starting with {2 is very unnatural in .mli files and I find the idea that you can simply ignore practice and educate users a bit arrogant. I have other things to do than changing in hundreds of published and unpublished .mli section headers to follow an unnatural convention for no obvious return.

I think a simpler way of achieving the stylistic unification you want between .mld and .mli without disturbing existing practice too much would be:

1. Restrict usage of {0 to a single usage and only in .mld files. This can then defines the contents of the title element. Stylistically this will matches the header for the module name in .mli files that is not definable by the user in these files.
2. In .mli files warn on {0 usage and simply map to {1. I don't think that he fact that {0 is available is a well known fact (I didn't until today).

[lpw25]

Another approach for mld files would be to support a @title tag. So users would just write:

@title This is the title
...

This somewhat depends on how the parser handles tags. The old parser would have placed the entire document under the @title tag with this scheme -- which is obviously not what we want -- but I suspect the new parser might be a little more sane in this regard.

[samoht]

I am not really looking forward to replace every occurence of {1 by {2 in the hundred of mirage packages. And it seems that the OCaml's stdlib will also need to be fixed.

I understand the rational of simplifying the ocamldoc/html mapping, but in this case I am not sure what we really gain. I always thought of these numbers as a way to classify section and sub-sections inside a file, not as a mapping to html sections. Starting by numbering these sections using {2 seems a bit weird. (and I didn't know about {0 as well).

[aantron]

I'm not committed to clamping to [2-4] by any means, but I would like to point out that odoc's own parser could be easily modified to walk through documentation in bulk and generate diffs for replacing {1 by {2, and adjusting lower-level sections accordingly. Of course, it's still work that might not be worth it, but you wouldn't have to manually replace every section level number.

[dbuenzli]

@aantron as others mention writing {2 in your .mli files is really not natural, whether or not you can automate the transition (besides you'd still break the look of the documentation of these packages until they release a new version).

[dbuenzli]

I'll soon start writing .mld files. I think it would be nice to have a resolution on this so that people don't have to change their files in the future.

Personally I think that this proposal is not too bad. I could do with @lpw25's proposal but I'd rather use sectioning element everywhere and finally I would really not like to write {2 in my .mli files.

[rizo]

I think your proposal makes sense. In particular it's a common HTML pattern to have multiple nested h1 tags per section: Using HTML sections and outlines / Defining headings. We already wrap the documentation blocks into sections in the generated HTML, so I think it also makes sense to use {1 ...} in mli and mld files.

Now that I'm sort of familiar with the current implementation after fixing #149, I could try to implement this (if @aantron or somebody else hasn't started already).

I do have one question based on another comment you made. You suggested that the heading levels should be shifted in produced HTML: {0 ...} results in h1, {1 ...} results in h2, etc. I don't see why this is necessary and find it a bit confusing. I prefer rendering both {0 ...} and {1 ...} as h1 and preserving the mapping for other levels. I understand that distinguishing between the main {0 ...} title and other {1 ...} titles is important but think this could be achived by either adding a class (.title?) to the first {0 ...}/h1 or by explicitly selectin the first direct h1 child of body in CSS.

What do you think?