New driving page #1209
New driving page #1209
Conversation
|
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...
panglesd
added
the
no changelog
|
I hope I clarified the confusion with the introduction of a new name for the |
|
Given we've just had a chat about not using submodules for sherlodoc, can you back out those changes please? |
|
Hmm, sorry I'm not sure to understand which change you are talking about! (wrong PR maybe?) |
.gitmodules
Outdated
| [submodule "sherlodoc"] | ||
| path = sherlodoc | ||
| url = https://github.com/Julow/sherlodoc | ||
| branch = odoc3_compat |
There was a problem hiding this comment.
Oh yes sorry, I accidentally pushed them when pushing the last commit.
There was a problem hiding this comment.
This PR branch now only contains the relevant commits. If you want to build the odoc doc with dune exec -- odoc_driver -p odoc, then use the new_driving_guide_work branch.
panglesd
force-pushed
the
new_driving_guide
branch
from
01ba5ea
to
da71f5e
Compare
doc/driver.mld
Outdated
| other trees, a [-L foo:<odoc_dir>/foo/lib/foo] argument needs to be added | ||
| at the link phase. | ||
|
|
||
| - A module tree named [foo.bar], with root id [foo/doc]. When referred from |
Thanks @gpetiot! Co-authored-by: Guillaume Petiot <[email protected]>
|
Thanks @gpetiot for the careful review! This documentation is likely to require some more updates, as we change the "canonical hierarchy" that we describe. |
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!