Render modules synopsis for {!modules:...}

[Julow]

Fixes #297

Resolve and render the synopsis of modules referenced with the {!modules:A B C} markup.

The first sentence of the first paragraph of the modules' documentation is taken. Headings, tags and other elements that are not paragraphs and lists are skipped, I think that's what ocamldoc does: https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-preamble

[Drup]

Looks good on my side 👍

@dbuenzli An opinion on the resulting HTML ?

[Julow]

I added the synopsis class too.

[dbuenzli]

According to what I see this uses definition lists, please don't use definitions list, they are needlessly hard to style. Use unordered lists as they were before.

Also there's no need to put the synopsis in its own paragraph as it should be only one paragraph; just span it after the module name (don't forget to add a space between the module name and the synopsis span).

Basically what you want is the same markup as odig's lists of packages. Mutatis mutandis that would be:

<ul class="modules">
  <li id="module-M">
    <a href="#module-M" class="anchor"></a>
    <a href="M/index.html"><code>M</code></a>
    <span class="synopsis">M's synopsis</span>
  </li>
</ul>

[Drup]

In general I agree, but if we should never use definition lists in HTML, I suggest we change the HTML renderer rather. The structure should be preserved internally (for the Latex output, for instance).

[dbuenzli]

I guess so, I was actually confused not to see anything in the HTML renderer so I eventually went to the samples (I'm not up-to-date with the intermediate representation business).

[dbuenzli]

The first sentence of the first paragraph of the modules' documentation is taken.

Detecting the first sentence is very unreliable. I think we had mostly agreed with @lpw25 that odoc would use the first paragraph. Here's a discussion about it.

[gasche]

Thanks @Julow for the implementation work!

I am fine with the "first paragraph" specification, I agree it is easier and it also sounds more convenient for users anyway -- what if I want several sentences in my synopsis? In practice I see people breaking the paragraph after the synopsis, so I think that most libraries would not notice any difference compared to ocamldoc's behavior.

[jonludlam]

Thanks for the reference, @dbuenzli - I'm much happier to use the first paragraph than try to figure out where the first sentence ends!

We should probably add this difference to our interfaces doc so it's clear we're behaving a little differently than ocamldoc here.

[Julow]

I've changed to "first paragraph".