You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This PR introduces new rules to build the documentation for all of the
dependent libraries used by a project, including those installed in the switch rather than in the workspace.
The primary target for this is to ensure we have up-to-date correct and complete docs for the workspace, both for browsing and for tooling to be able to query.
A few decisions made during this:
Only libraries that are used by the projects in the workspace are documented.
There's no attempt made to document the entire switch. This has some
interesting consequences - for example, documentation files (mlds) are associated with packages rather than libraries and may well assume the existence of all their libraries.
Odoc file locations
The odoc files produced from the cmti/cmt/cmi files in the switch are put into 'equivalent' dirs under _build - specifically if a cmti file is in <opam-switch>/lib/foo/bar then the odoc file will be in _build/default/_doc/odoc/external/foo/bar. This is done to ensure consistency between odoc's view of the world and ocaml's, as odoc uses the same strategy as ocaml for finding modules, that is, an include path.
Non-dune packages
There's a bare-minimum level of effort put into handling non-dune packages. Essentially I've not tried to separate things into separate libraries, and the packages are just treated like a big bag of modules.
Unwrapped libraries
These are also treated like the non-dune packages - this is mainly because I couldn't see a good way to get a Modules.t value.
Private libraries
Since the primary target is for the developer working on the codebase, I'm building docs for the private libraries by default.
Still to do:
This is a draft right now - I've not updated the tests. In addition, there's other work to be done - possibly in this PR or a follow-up.
make the index pages more interesting (ie, more metadata to document).
silence the warnings coming from files that aren't in the workspace
Add a symlink from the previous docs output directory (or possibly a 403 page!)
Good question about bin_prot. The superficial answer is that I dont have a Modules.t value for it - and I believe that's because in the installed dune-package file there's only:
For the inline test libraries, I agree it would be nice to exclude them. That'll be pretty easy if I can identify them precisely -- do you know the best way to do this?
The big change since the first iteration of this is that dune build @doc now does something pretty similar to what currently happens -- ie, building the docs for the local packages -- whereas dune build @doc-all builds all of the docs. I've also made more use of aliases for the html output to avoid unnecessary 'fake' dependencies. I've been testing it with --sandbox xxx to see if that works, but something is going wrong there at the link phase, and I'm not sure I know the best way to debug this.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
odocIssues and PRs related to documentation generation with odoc
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces new rules to build the documentation for all of the
dependent libraries used by a project, including those installed in the switch rather than in the workspace.
The primary target for this is to ensure we have up-to-date correct and complete docs for the workspace, both for browsing and for tooling to be able to query.
A few decisions made during this:
There's no attempt made to document the entire switch. This has some
interesting consequences - for example, documentation files (mlds) are associated with packages rather than libraries and may well assume the existence of all their libraries.
The odoc files produced from the cmti/cmt/cmi files in the switch are put into 'equivalent' dirs under
_build- specifically if a cmti file is in<opam-switch>/lib/foo/barthen the odoc file will be in_build/default/_doc/odoc/external/foo/bar. This is done to ensure consistency between odoc's view of the world and ocaml's, as odoc uses the same strategy as ocaml for finding modules, that is, an include path.There's a bare-minimum level of effort put into handling non-dune packages. Essentially I've not tried to separate things into separate libraries, and the packages are just treated like a big bag of modules.
These are also treated like the non-dune packages - this is mainly because I couldn't see a good way to get a
Modules.tvalue.Since the primary target is for the developer working on the codebase, I'm building docs for the private libraries by default.
Still to do:
This is a draft right now - I've not updated the tests. In addition, there's other work to be done - possibly in this PR or a follow-up.