See ocaml-doc/doc-ock-html#5 for details and discussion.

There are still a few problems with cross references ({{!U.id}text} ocamldoc syntax).

1. It seems that you cannot refer to yourself in a compilation unit U which the ocamldoc language allows (i.e. references of the form {{!U.id}text}) in the doc strings of U itself). Not sure whether this was a good idea in the first place though. (E.g. in ocamldoc the second Ptime in this module preamble links to iteself, not very useful in this case though).
2. References to other compilation units that a unit formally doesn't depend on are not resolved
   (e.g. Ptime_clock in this module preamble). This concerns intra and inter package references.
3. In ocamldoc {!U.id} resolution first looks for a module specification U.id and then for a documentation section id anchor. It seems to be the converse in odoc (see this reference, src, target)
4. When a reference {{!U.id}text} is unresolved, U.id is spliced in. text should instead, spanned with a xref-unresolved class so that I can be made visible through CSS. Adding a title attribute to the span with the text unresolved $id allows to show the unresolved reference in a tool tip.

I think this is for octavius aswell:

> opkg odoc react
Error src/react.mli, line 207, col 26 to line 207, col 27: '}' expected

The line is here and I guess it wants to complain about the . that is outside the list element.

It's not what you expect when you click on it (I would rather expect to see the implementation if it existed).

At least land, lor, lxor, lsl, lsr, asr. See:

http://docs.mirage.io/react/React/S/Int/index.html#val-land
http://erratique.ch/software/react/doc/React.S.Int.html#VAL(land)

That's pretty specific. But I suspect it's because you process the links at the wrong hierarchical level. In fact you have to process them twice, once for injecting the synopsis into the parent module page and once for the module page itself.

(** Heyho {!sectionid} *)
module Let's_go : sig
  (** {1:sectionid} *)
end

That {!sectionid} link is broken on the Let's_go page (it is correct though in the synopsis of the parent page).

This can be seen here (references to modules)

http://docs.mirage.io/astring/Astring/String/index.html
http://erratique.ch/software/astring/doc/Astring.String.html

and here the examples link (reference to a section)

http://docs.mirage.io/uucp/Uucp/Case/index.html
http://erratique.ch/software/uucp/doc/Uucp.Case.html

In ocamldoc if one writes a direct reference to a section ({!sectionid} vs {{!sectionid}linked text}) the section title is spliced into the content. odoc does not do this but instead splices sectionid in the content.

Contrast for example the bullet list here:

http://docs.mirage.io/topkg/Topkg/index.html#basics
http://erratique.ch/software/topkg/doc/Topkg.html#basics

It makes stylesheets a nightmare to develop.

For example here http://docs.mirage.io/odoc/ocaml/Scanf/index.html you have:

<div class="doc"><h6>...</h6></div>
<div class="doc"><h6>...</h6></div>

Not only does this divitis prevents me of writing simple css rules like (h6 + h6) the added tags are purely worthless.

Basically a mli rendered to html should be seen as a literate document where you a proper document interleaved with properly delineated formal definitions.

Also this div wrapping seems random. For example it doesn't appear here:

http://docs.mirage.io/odoc/react/React/index.html#basics

(where we do see however horrible br and lack of p (#10))

is a span with style='font-style: italic' attribute. It should be a em tag.

Html has paragraphs. Paragraphs should delimited by a blank line or by a markup level block. See here http://caml.inria.fr/mantis/view.php?id=7352#c16283

These are:

• include M (example)
• The braces of records ([example] (http://docs.mirage.io/ocaml/Complex/index.html#type-t))
• Type constraints (constraint 'a = ..., there's an example in the vg package, couldn't quickly find one on docs.mirage.io).

Currently odoc generates links to mod/, however this doesn't work if the html files are not being served by an HTTP server (which is the expected use case e.g. for OPAM). In the latter case the links should be mod/index.html, so that the pages can be browsed through the file protocol.

I'd suggest to always generate direct links and have a --pretty-uri or --semantic-uri or --clean-uri option (these names were taken from here) that generates webpages with non direct links.

Title was: odoc drops a good part of fpath:fpath.mli

Compare ocamldoc with odoc (just before the tips section).

Reported in #33 .

This is needed on mobile for adapting to devices. Each page should have the following in the page header.

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

are not hyperlinked and references to identifiers not wrapped in a code tag.

Contrast the links in the preamble of this module:

http://docs.mirage.io/odoc/astring/Astring/index.html
http://docs.mirage.io/astring/Astring.html

Contrast the doc string of the two first values in the String section here:

http://docs.mirage.io/odoc/astring/Astring/index.html
http://docs.mirage.io/astring/Astring.html

opam install gg && opkg odoc gg
opkg: [WARNING] gg: /Users/dbuenzli/.opam/4.03.0/lib/gg/gg.cmti: No cmti found for Unix (331e41ad213579d006efd84f19005bd5)
opkg: [WARNING] gg: /Users/dbuenzli/.opam/4.03.0/lib/gg/gg.cmti: No cmti found for Bigarray (7cb259b8efbf4550648d25651a3342ee)
Error src/gg.mli, line 3225, col 28 to line 3225, col 30: unmatched 'v}'
Error src/gg.mli, line 3228, col 45 to line 3228, col 47: unmatched 'v}'
Error src/gg.mli, line 3238, col 35 to line 3238, col 37: unmatched 'v}'
Error src/gg.mli, line 3241, col 55 to line 3241, col 57: unmatched 'v}'

The corresponding lines are here:

https://github.com/dbuenzli/gg/blob/master/src/gg.mli#L3225
https://github.com/dbuenzli/gg/blob/master/src/gg.mli#L3228
https://github.com/dbuenzli/gg/blob/master/src/gg.mli#L3238
https://github.com/dbuenzli/gg/blob/master/src/gg.mli#L3241

Asetmap has no toplevel module Asetmap : sig ... end definition.

Asetmap.Set has a module Set : sig end definition.

This should be unified, I would be in favor of dropping the module Set : sig end as it is kind of redundant.

Cf. #3

1. If we keep the embedding ability (see #9) then the wrapping <div class='odoc-doc'> should be replaced by an <article class='odoc'> (semantics).
2. The introductory <div class=intro> should by simply be replaced by a classless <header> tag which can be used for introductory contents.
3. After the header tag there should be no enclosing div for the literate text and definitions, simply add them sequentially after the header tag.

This is certainly due to an underspecification of the ocamldoc language. As you can see here:

http://docs.mirage.io/cmdliner/Cmdliner/index.html#basics
http://erratique.ch/software/cmdliner/doc/Cmdliner#basics

The first code fence has no initial white line, but the second has. This is the result of writing the first one as:

{[mycode]}

and the second one as:

{[
mycode]}

or

{[
mycode
]}

The last two forms are essential for code fences and verbatims that span more than one-line otherwise you cannot write your code sample properly aligned and indented in your sources which makes the source less readable:

{[let x = 3
let y = 4]}

you really want to write:

{[
let x = 3
let y = 3
]}

I'm not sure which rules ocamldoc follows exactly but my gut feeling is that you should simply ignore a newline just after {[ and {v and just before ]} and v}.

(This is not visible for trailing newlines in the html because at that point you end up a block-level element anyways).

Quite surprisingly, as far as I know this is not an attachement problem:

http://docs.mirage.io/react/React/E/index.html#val-select
http://erratique.ch/software/react/doc/React.E.html#VALselect

The source is here

https://github.com/dbuenzli/react/blob/1a4a86e4fa8d67bd59c77cc3180a1718fdb84b18/src/react.mli#L201-L208

Parsing errors should be reported as warnings on stderr. It might also be a good idea to put them in the docs themselves to make the problem obvious.

See
http://docs.mirage.io/rresult/Rresult/R/index.html#val-get_error

The text should read:

get_error r is e if r = Error e and Raises Invalid_argument otherwise.

Also the return and fail look odd below, as they are not in the ocamldoc version.

Note the following is about definitions not code fences.

The markup for definitions could be more semantic and the layout should be improved as it can be pretty bad on long definitions since it may wrap anywhere, something a sensitive OCaml programmer would never do.

First these things would be good to have:

1. The whole definition should be wrapped by a <code> tag.
2. The identifier being defined should be classified via a <span>.
3. The constructors of variants should be classified via a <span> the same way they are classified in textual code spans.

Regarding the layout there are at least two solutions that can be tried.

a) <pre> can be used instead of <div class="def"> and all the formatting is done manually (this is the way ocamldoc proceeds), the disadvantage is that it will not be responsive to the page width.

b) <div class = "def"> is kept but we try to control the line breaking algorithm by only using spaces at the places where we would like to break (e.g. before |, after ->) and using non breaking spaces U+00A0 where we don't want to break. I should then be able to make an indent via css' text-indent.

I have a slight preference to try what b) can give us.

Click the Ord argument here http://docs.mirage.io/odoc/asetmap/Asetmap/Set/index.html

I'd like to give direct links in that nav tag to the package list and to the package page. That is
rather than simply have : Up, you'd get at any level packages - pkg vX.Y.Z - Up.

The markup you want to add here seems sufficiently small to be specified on the cli rather than read from a file.

That is when we write {!M.x} and x is the identifier of a module specification, the content of the link should be wrapped in a code element.

See also #37.

There are two problems:

Module specifications. The current strategy for module specifications is to generate an empty anchor at the beginning of the div wrapping the spec. Using CSS trickery hovering over the div of the specification reveals an out of div hash one can click to anchor to the specification. Aiming at this hash turns out to be a bit tricky and frustrating. I suggest we try to put the anchor around the keyword (module, type, val, etc.) so that one can click on the keyword to anchor to the def.

Headers. No anchors are being generated. Those being a bit bigger maybe starting the header with an empty anchor like we do now will be enough otherwise we could try to anchor the first letter or the first word.

Note that much better would be in each case make the anchor wraps the whole element (div or h1, allowed by html5) so that a click on it anchors. However this conflicts with the ability to select the information for cut and paste or personal highlighting.

See for example:

http://docs.mirage.io/logs/Logs/index.html#module-type-LOG
http://docs.mirage.io/logs/Logs/module-type-LOG/index.html

The markup generated for module preambles is different for 1) toplevel modules (compilation units) and 2) submodules:

<header>
  <h1>module Mod</h1>
</header>
<p>preamble</p>
<p>preamble</p>
...

<header>
  <h1>module Mod.Sub</h1>
</header>
<div class="mod">
  <div class="def"><code>module Mod.Sub : sig ... end</code></div> 
  <div class="doc"><p>preamble</p>...</div>
</div>

This should be discussed and a unifying scheme should be found which should take into account functors and the rendering of their arguments.

Current CSS handling is sub-optimal, a link to a CSS file called odoc.css located above --output-dir is generated in the HTML.

Here's a suggested approach:

1. By default the link to the CSS file should be odoc.css in the --output-dir. A default CSS file located in etc should be copied over in the --output-dir. These instructions show how topkg can be used to work with an etc directory both in release and development mode.
2. A --css-uri URI option should be added to override the default CSS link (odoc.css) generated in the HTML.
3. A --css-file FILE option should be added to be able to specify the contents of the odoc.css file in --output-dir
4. A --no-css-file option should be added to specify that no CSS file should be copied over to --output-dir.

Exceptions are not well marked up. See for example http://docs.mirage.io/odoc/alcotest/Alcotest/index.html

1. They are not in a <div class="region"> block but in a <div class="exn">.
2. They use invalid ocaml syntax to render, the keyword for exceptions is exception not exn.
3. They lack an anchor for referencing.

Related to the general structure #18 and #19 I would prefer if we drop the region class. I think each definition should be marked up as follows:

<div class = "spec $(KIND)">
  <a href="#$(KIND)-$(ID)" class="anchor"></a>
  <div class="def $(KIND)"><code>...</code></div>
  <div class="doc">...</div>
</div>

Where $(KIND) is the kind of construct. spec comes from the vocabulary of the module system.

Regarding anchor fragments I find #/$(ID).$(kind) to be noisy in practice. In the above proposal I dropped the / and also reversed the $(KIND) and $(ID) as it then matches the order we write them in OCaml. Replaced the . by - to avoid confusion with OCaml paths.

Everything gets generated (and overwritten around) in the same toplevel directory.

see
http://docs.mirage.io/odoc/omd/Omd/index.html
vs the ocamldoc equivalent:
http://docs.mirage.io/omd/Omd.html

The rendering seems to be oddly placed in Safari in the omd version, with the comments being squeezed to the right hand size.

Examples:

http://docs.mirage.io/doc-ock/Ocamlary/index.html#type-variant
http://docs.mirage.io/doc-ock/Ocamlary/index.html#type-poly_variant

The markup should follow what was proposed for record (#50), which means:

1. The table tag should be classified with variant (I don't think we should distinguish polyvars what do you think ?)
2. Remove cons class from tr.
3. Each row should have only two td columns per row and no inner div. The first td should have the as attribute the the id that the current inner div has, be classified with def constructor and simply contain the anchor and the constructor definition as you would render a function type. The second td should have the comment and the class doc.
4. This should be done for polymorphic variant type definitions (but now for the polyvars that occur in function signatures).

I'm getting headache at reading the css selectors. Also I wonder if the plan is still to assume that odoc is in its own div rather than on the whole page otherwise we could simply remove this (better to have simple structures for layout).

Currently the -I $DIR option requires $DIR to exist. I'm not sure this is a good idea. Any reason why this is the case ?

The fact that odoc compile doesn't allow to choose the name of the output file is a bit strange. If I'm not mistaken odoc compile can only output a single file, so the fact that -o specifies an output directory is a little bit odd. Here's what I would expect from a cli point of view:

odoc compile bla.cmti                  # Generates bla.odoc in the cwd
odoc compile -o path/to/file bla.cmti  # Generates the output in path/to/file
odoc compile -o - bla.cmti             # Generates output on stdout. 

cf. #12 (comment)

See the first bullet in the docstring of this element

http://docs.mirage.io/react/React/S/index.html#val-fix
http://erratique.ch/software/react/doc/React.S.html#VALfix

Source:

https://github.com/dbuenzli/react/blob/1a4a86e4fa8d67bd59c77cc3180a1718fdb84b18/src/react.mli#L485-L497

The link for t in module M : S with type t = ... links to M.t when it should probably link to S.t instead.

For example, in http://docs.mirage.io/asetmap/Asetmap/Set/index.html the elt link tries to go to Make.elt (which doesn't exist due to #13) whereas it should link to S.elt.

Example here http://docs.mirage.io/doc-ock/Ocamlary/index.html#type-record

Should be simplified and better classified. I suggest:

1. classifying the the table tag as record.
2. Removing the field class from the table row tr.
3. Each row should have only two td columns per row and no inner div as is the case now. The first td should have as attribute the id that the current inner div has, be classified with def field and simply contain the anchor and the field definition rendered as you would render a fun sig. The second td should have the comment and should have the class doc.

providing a way to generate one would be nice.

<details> tags have a significant usability problem in the sense that they break fragment linking and on-page search. Besides I think that in general you are interested in seeing all the defs available to you. Hence I would suggest to generate pages with the open tag set.

This way fragment linking and page search will work when the page is loaded and it will still provide a way for users to quickly hide common definitions if needed.

In #33 @dbuenzli noticed that sometimes the "text" part of a link is lost when the reference is unresolved, compare for example :

• http://erratique.ch/software/fpath/doc/Fpath (ocamldoc)
• http://docs.mirage.io/fpath/Fpath/index.html (odoc)

where "important tips" is lost and truncated to "tips".

This is a "known problem", see this FIXME.

The problem is that we're trying a "best effort" approach where if the path we are pointing to is not resolved but some prefix of it is, we will still make the prefix clickable. In such cases however, we display the path and drop the user supplied text.

We could do a bit better than what we are doing now, i.e. only do that when we know that some part of the path is resolved, otherwise if none of it is, just display the user text. But it's not great.

Maybe we should just not try to link if a path is not completely resolved?

Regardless, do we want some kind of markup to indicate that "oh, we failed to resolve that reference"?

For example in uuidm we have this stop comment:

https://github.com/dbuenzli/uuidm/blob/master/src/uuidm.mli#L38-L41

create still shows up in odoc's API doc with dubious C multiline start comments.

opam install uuidm && opkg ocamldoc uuidm && opkg odoc uuidm && opkg doc -c uuidm

When you develop your package locally you'd like to be able to generate its documentation in its say _build directory but also to check the accuracy of external links against the current switch docs.

For this we need an option to specify the base URI to use for resolving links to other packages (typically this base uri will be a relative file path to $(opkg cache path)/odoc).

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.

I just noticed that odoc generates <hr> tags (is that new ?) after the preamble of submodule pages. See for example here http://docs.mirage.io/odoc/astring/Astring/Char/index.html

Don't do this, such lines can be (and are) introduced via the stylesheet.

rather than spans tagged with class sup and sub. No need to be special.