odoc listings is not of great use for odig's package pages

[dbuenzli]

In odig I generate these pages myself because I enrich them with meta-data about packages. In its current form odoc listing is anyway not as good as what ocamldoc does because it doesn't generate module synopses in the toplevel list. So you will have to take a list of odoc files rather than string items as it is now.

A better try at this would be to take a list of .odoc files and generate markup fragment for the list of toplevel module with their synopses on stdout (or in a file).

Alternatively simply copy what ocamldoc does with its -intro page option which allowed me to solve the problem in the ocamldoc path.

I tend to think that the intro thing will be better if odoc starts generating index of symbols for packages like ocamldoc does.

[dbuenzli]

(Note that currently opkg doesn't use listings at all)

[trefis]

I started working on this, I plan to just remove listings and have a new command mimicking -intro.

[dbuenzli]

We should discuss this, this is important because for now in odig's odoc's backend we miss the toplevel module synopses on the package page which is bad for user orientation.

[dbuenzli]

Also the ability to generate a page with all identifiers of the package is very useful, it nicely takes care of the lack of general search by piggy-backing on your browser in page search.

I don't think separating $(KIND) of identifiers like ocamldoc does is useful we can make that distinction in the index entry on the same page. For the markup you can for example have a look at odig's package list by name. So basically a page with a list of identifiers whose elements are:

<ol class="id-index">
 ...
  <li id="id-i">
   <ol>
    <li>
       <a class="id $(KIND)" href="...">identifier</a>
       <a class="id path" href="...">Mod.Path</a>
       <span="id doc">first few words of the doc string for context...</span>
    <li>
    ...
   </ol>
  </li>
 ...
</ol>

[trefis]

I just added a new optional flag to odoc html mimicking the -intro flag of ocamldoc.
One uses it in this way:

$ odoc html [-I DIR [-I DIR [...]]] -o ODIR --intro-for PACKAGE_NAME some_file.mld

And it will generate an index.html file in ODIR.
The -I are necessary to be able to resolve the references present inside some_file.mld.

The {!modules: ...} still works as it did with ocamldoc.
So unless there is a problem with {%html ...%} you should be able to reproduce the scheme you use with ocamldoc.

I will push a commit removing the listing subcommand (which is now useless) soon and closing this issue at the same time.
Please open another issue if you have remarks regarding this new --intro-for flag.
I will open another issue to track progress regarding the generation of an index page.

[dbuenzli]

That looks perfect, thanks !