Document required invocations for building docs, and a reference driver.

[jonludlam]

The way in which odoc should be invoked will be changing as part of the integration of the new model and the new latex/man page generators.

Currently odoc is usually driven by a variety of systems including odig, dune and bsdoc. The exact sequence of calls required is not simple or obvious, and we will be introducing a new link step that sits between the compilation and generation phases.

It's clear we need to document this carefully, but I'd also like to go a step further and produce a 'reference driver' that will execute odoc in the correct sequence. It's likely to be some form of Makefile generation. This is useful for several reasons:

1. Validation of the documentation
2. Development while the new invocations are being worked on
3. Testing

[yawaramin]

It's clear we need to document this carefully, but I'd also like to go a step further and produce a 'reference driver' that will execute odoc in the correct sequence. It's likely to be some form of Makefile generation.

I just re-read this; it seems we are thinking along similar lines right now. I mentioned in reasonml-community/bsdoc#18 that I am planning to use BuckleScript's vendored Ninja build tool, which you may have heard of because it's actually a separate tool that BuckleScript just happens to bundle. I think it's worth a look–Ninja build rules are simple, and the build is super fast–it's part of what makes BuckleScript itself so fast.

For example, here's a rule and target I wrote to build the support files:

rule support_files
  command = $odoc support-files --output-dir=$output_dir # actual executed command
  description = odoc support-files # user-friendly description of command

# build a target: 'build OUTPUT1 [... OUTPUTn]: RULE_NAME [INPUT1 [... INPUTn]]'
build $output_dir/odoc.css $output_dir/highlight.pack.js: support_files

If you're interested, I can send more of this sample Ninja build file I hand-wrote while learning the format.

[dbuenzli]

For example, here's a rule and target

You should not hard-code support-files's outputs, use odoc support-files-targets to determine which files the command writes.

[yawaramin]

@dbuenzli thanks, good to know. Will do.

[jonludlam]

A start: https://github.com/jonludlam/odoc/commits/reference-driver-v2