Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
odoc should drive itself #137
Building odoc's output requires calling the odoc binary many times, about twice per
odoc compile [OPTIONS] foo.cmti odoc html [OPTIONS] foo.odoc # For each .cmti file
In addition, the commands have to be issued in a correct order, determined by the OCaml dependencies between the
This has several negative effects:
The information needed for odoc to drive itself is mostly already contained in the
I'm a little bit unsure about all this; also you are conflating many different things in the same issue which deserve an orthogonal treatement (e.g. indexes).
You basically want to turn
What should be done is to make it more build system friendly and one important point for this would be to solve #81 as
I agree mostly agree with @dbuenzli, although I do think there is room for having a simpler command for letting users run odoc themselves in simple situations. As long as the original
So, by all means make it easy for users to directly run odoc without needing to learn how it works with a command that handles things for them, but it will make life harder for the build systems if you take out the existing commands.
+1 to a higher level workflow without removing low level commands.
Why can't an
As a casual user, I'd be able to just run
As an expert user, I'd be able to track each compilation step of the documentation as I see fit — all the control.
First of all, to make sure everyone is on the same page let me just state the basics (bare with me please if this is too obvious):
Please correct me if any of these statements are wrong in any way. This is just my understanding constructed from fragmented discussions and source code.
I personally agree that the duplication of efforts between odig, dune and soon bsb, as well as lack of high-level view of the package, have negative consequences to the overall development process and design of user-facing features like package module index, search, alternative backends, etc.
To me it's less of a "who drives odoc" problem and more a "how to ensure a great user experience" problem.
Ideally, from the user perspective (and I understand this is out of odoc's scope, but where else should this be discussed?), we should try to produce an informative and organized package page (with all package versions) similar to the one produced by Hackage or Rust Docs. I've given these examples before, but please consider again how hard it would be to implement something like that with the current state of tooling. Sure, odig does produce nice package pages with metadata and a module list, but dune doesn't. Also how does OPAM's package pages relate to all of this? Do we want to further aggravate the user experience with bsb building it's own package index page?
I think that regardless of whether odoc will or will not "drive itself", many of these issues could be addressed with a "package" definition that would include module list (like the one generated here) and metadata. This would essentially allow odoc to generate the HTML for the index page in a consistent and independent way for all build environments.
referenced this issue
Sep 20, 2018
I'm not sure how much duplication of effort there actually is. The main parts of writing build rules for
Things like the module index aren't really about whether odoc "drives itself". I think those tools make there own index pages because they want to/ odoc doesn't provide a builtin command that does it. Although to a certain extent the