odoc
odoc copied to clipboard
ocaml
`odoc html` allow to specify the base URI for resolving links to external identifiers.
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).
No, I didn't explicitly consider this. It should be possible to add with some effort, though. I think my refactoring was mostly orthogonal to this issue.
Ok thanks for the answer. I don't think this is a complex problem as long as you carefully isolate the functions that generate links. It would be nice to have though so that you can properly test inter-package links.
Things don't seem to have changed to much in that area during the reorganization, and it should indeed be relatively easy to change from what I can see.
I'm considering implementing this feature. What would be the best place to start? Any pointers would be very appreciated as, given the current implementation, I don't see a clean and easy way to parametrise the base URI. The code base seems to pervasively assume that there's a root package.
This is needed to implement HTML fragments that don't belong to a particular package and can set the root to the docsets path for cross-reference resolution. See https://github.com/ocaml/odoc/pull/166#issuecomment-415421238 for more details.
@dbuenzli Can we decide the interface for this feature? I might be able to implement partial support for fragments.
It seems like if I intercept the Html.Html_tree.Relative_link.Id.href function call during HTML generation I can supply a custom base URI.
What about?
$ odoc html-fragment --root-uri=URI -o FRAGMENT.html -I INCLUDE_DIR PAGE.mld
This is for the html-fragment, we could add it later to other commands too.
As a side note (and to remind myself), it would be useful if this option could be integrated with dune when it's done.
Update: I implemented a limited support for the --root-uri option for the proposed html-fragment command in https://github.com/ocaml/odoc/pull/166/commits/71f4a3e7e9cbc477130b697bd46015254d630d72. Still need to polish some things, but feedback is welcome!
Great ! I'm a little bit unsure about the --root-uri name though, when I read the cli it seems to me that it defines the root of the generated document and that's not the case, it defines the URI w.r.t. to which cross-references are resolved in the resulting document. Maybe --xref-root-uri or --xref-base-uri or --xref-uri ?
Update: This is partially solved by https://github.com/ocaml/odoc/pull/166, i.e., the odoc html-fragment command accepts the --root-uri option. This is not implemented for the odoc html command yet. I'll try to implement this later when other more critical issues are solved.
@dbuenzli sorry I forgot about your suggestion to change the name of --root-uri in my fragment PR. Would you like me to change it to one of your options? Which one?
Pick the one you prefer but I think the one that is maybe the most terminology correct is --xref-base-uri.