[ocaml-platform] codoc 0.2.0: an alpha release of a new OCaml documentation generator

[David Sheets]

Hello,

Yesterday, OCaml Labs published an alpha version of a new OCaml 
documentation generator, codoc 0.2.0 <https://github.com/dsheets/codoc>. 
To try it out, simply follow the directions in the README on that page. 
For a sample of the current, default output of the tool, see 
<http://dsheets.github.io/codoc/>.

codoc's aim is to provide a widely useful set of tools for generating 
OCaml documentation. In particular, we've strived to:

1. Cover all of OCaml's features
2. Provide accurate name resolution and linking
3. Support cross-linking between different packages
4. Expose interfaces to the components we've used to build codoc
5. Provide a magic-free command-line interface to the tool itself
6. Reduce external dependencies and default integration with other tools

We haven't yet achieved all of these at all levels of our tool stack but 
we are getting close. codoc 0.2.0 is usable today (if a little rough in 
some areas like default CSS).

Please keep in mind that codoc, doc-ock-lib, and doc-ock-xml are still 
under heavy development and are not feature complete. Notably, there are 
some important outstanding issues:

1. Class and class type documentation has no generated HTML 
<https://github.com/dsheets/codoc/issues/9>
2. CSS is subpar (<https://github.com/dsheets/codoc/issues/22> and others)
3. codoc html does not understand --package 
<https://github.com/dsheets/codoc/issues/42>
4. opam doc is too invasive (temporary for demonstration purposes; 
tracked by <https://github.com/dsheets/codoc/issues/48>)
5. Documentation syntax errors are not reported in the correct phase or 
obviously enough <https://github.com/dsheets/codoc/issues/58> 
<https://github.com/lpw25/doc-ock-lib/issues/48>
6. Character sets are not handled correctly 
<https://github.com/lpw25/doc-ock-lib/issues/43>
7. -pack and cmt extraction are not supported 
<https://github.com/lpw25/doc-ock-lib/issues/35> and 
<https://github.com/lpw25/doc-ock-lib/issues/3>
8. Inclusion/substitution is not supported 
<https://github.com/lpw25/doc-ock-lib/issues/2>

The developers are very happy to take suggestions, comments, complaints, 
bug reports, and patches at <https://github.com/dsheets/codoc/issues>. 
We do hope that you'll let us know what you think and help us build a 
next generation documentation tool which will serve our community admirably.

Keep Caml and Curry On,

David Sheets