New driving page #1209
New driving page #1209
Conversation
Quoting the docs of the Findlib library: > * Furthermore, the environment variables OCAMLPATH, OCAMLFIND_DESTDIR, > * OCAMLFIND_COMMANDS, OCAMLFIND_IGNORE_DUPS_IN, and CAMLLIB are interpreted. > * By default, the function takes > * the values found in the environment, but you can pass different values > * using the [env_*] arguments. By setting these values to empty strings > * they are no longer considered. So when we do ``` dune exec -- odoc_driver -p odoc ``` findlib finds the `odoc` library in `_build/install` in some part of the codebase, in `<opam switch>/lib/odoc` in some other parts of the code, which results in the docs for `odoc` not being built. This changes to consistently find the `<opam switch>/lib/odoc`.
|
The page can be consulted rendered here. As always I'll try to keep it up to date, but no guarantee. |
doc/driver.mld
Outdated
| package. Any of its libraries will have an associated "module unit", with the | ||
| name of the library. Another package can refer to the doc using the package |
There was a problem hiding this comment.
I wasn't quite clear here what the module unit does? Is it the page for the module that is the library itself? Is a submodule not also a module unit? If it isn't, might we call module units library units instead (since only whole libraries have them)?
There was a problem hiding this comment.
Thanks for the review!
I named it "module unit" since it contains modules, just as a "page unit" contains page.
However, the "unit" name is very confusing I think, and was a bad choice, since we already have "OCaml compilation units" for .cm{t;ti;i} and sometimes "odoc units" for .odoc.
I'll update that to hopefully something less confusing!
doc/driver.mld
Outdated
| - [-L <name>:<dir>] are used to list the "named module-units", used to resolve | ||
| references such as [{!/findlib.dynload/Fl_dynload}]. | ||
|
|
||
| - [-I <dir>] are used to resolve non-references, and should include the same set |
There was a problem hiding this comment.
I'm not sure what a non-reference is? Especially if it's still something that can be resolved?
There was a problem hiding this comment.
This is indeed confusing. I'm not even sure what I wanted to say...
Co-authored-by: Luke Maurer <[email protected]>
Checked-out to branch odoc3_compat of https://github.com/Julow/sherlodoc
The driver runs on Base. This will also test that sherlodoc is co-installable with odoc.
panglesd
added
the
no changelog
|
I hope I clarified the confusion with the introduction of a new name for the |
This new driving page contains everything one should know to write an odoc 3.0 driver, including to drive doc generation for opam-installed package.
Unfortunately, I feel the style is not great... And I'm not sure everything is clear... but at least the structure of the explanation is there.
It explains the current status of the CLI (assuming #1206 is merged), and should be updated when new changes are added.
It is also a good time for the community to give feedback!