search

dsheets / codoc

OCaml documentation generator
34 stars 5 forks source link

Support for sample code extraction #74

Closed dbuenzli closed 4 years ago

dbuenzli commented 9 years ago

In my libraries I often provide sample code, sometimes it's only snippets separated by comments in a litterate programming fashion (see e.g. Vg's basics) sometimes it is full working examples (see e.g. Cmdliner's full examples).

Usually I have a copy of this code in my test/ directory (they are part of the test compilation target) and I install that in the documentation directory of the package, see e.g.: 

> ls $(opam config var cmdliner:doc)
CHANGES.md  chorus.ml   darcs_ex.ml rm_ex.ml
README.md   cp_ex.ml    revolt.ml   tail_ex.ml

The problem is of course that this sample code is not type-checked and needs to be kept in sync with the files manually which from a maintenance point of view is error-prone an painful in general. Still I think that this way of doing is the right way (i.e. always keep all documentation bits with the mli themselves).

It would be nice if some kind of code extraction facility could be provided by the tool. However I don't see how this could be done without extending the ocamldoc language.

The idea would be that code fences ({[ ... ]}) should support arbitrary identifiers of some sort e.g. {$ID[ ... ]} if that's possible parsing-wise. codoc would then provide a code-extract command, that provided with an identifiers would extract and cat all the fences with that identifiers. This would allow to build the sources of the sample code by doing a codoc code-extract $ID m.xml > examples.ml.

I guess this doesn't strictly belongs to codoc but I'm filing this here since this is the end-user front-end. Feel free to direct me to the appropriate bug tracker(s).

dsheets commented 9 years ago

This sounds like a good idea and I believe this is the appropriate repository. I'm swapping into codoc soon and code snippet handling is perhaps the largest embedded content issue as far as I can tell.

See http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec328 for the feature that could be co-opted to support this.

Drup commented 9 years ago

I agree, that would be very nice. As a bonus, it could propose opening a custom jsoo toplevel with the code (like this) but maybe that should be a plugin...