odoc
odoc copied to clipboard
ocaml
Improvements to the manpage
I updated the documentation for some commands and added consistency. Sub commands are grouped and sorted in sections, to show the useful commands first. I also updated some doc strings.
I added some documentation about dependency between compile and link phases.
The last commit concatenate the output of all --help into one page in the documentation. It's not easy to navigate because it's big and the TOC is not very readable. I'm considering generating a different page for each subcommand, what do you think?
I've changed the manpage generator tool to parse odoc --help and extract more information: order of the commands, sections, summaries.
Something is going wrong on macOS - CI is failing and I've seen a similar thing locally too.
I've removed the manpage parsing from the runtest alias, so it cannot break the tests now. This can be improved after the release.
I'd really really prefer not to be parsing the man output. I'd far rather work with the Cmdliner types and generate the mld file from them, but I think it's not possible today as the types are opaque. @dbuenzli do you have any suggestions? would you be receptive to either a new help output format -- 'mld' -- in cmdliner, or exposing something to allow this to be done more nicely?
would you be receptive to either a new help output format -- 'mld' -- in cmdliner, or exposing something to allow this to be done more nicely?
No. I'm a bit dubious about the usefulness of all this.
Man pages are a terrible documentation medium. Keep them at the minimum as the reference for the cli interface and have good high-level docs. I doubt there's much value in having them alongside the .mld files.
If you really have to then odoc --help=groff | groff -Thtml is your friend.
We can pass the values around without going through cmdliner and without parsing but as @dbuenzli says, perhaps it's not so useful ?
We can merge the improvements to the documentation without this, before the release: https://github.com/ocaml/odoc/pull/912