[not really an issue] How does Owl generate its documentation?

[chetmurthy]

I'd like to shamelessly plagiarize the way that Owl generates its documentation, but am having trouble finding it. I had read elsewhere (over at ocaml/odoc ?) that Owl used sphinx for documentation, but generated some part with odoc? Could you point me to that? b/c that's what I'd like to do!

[dbuenzli]

This is likely not the a good place to discuss this but @chetmurthy did you consider using .mld files ?

You get the same documentation language as the one you write in your .mli file, checked cross references between your manuals and APIs, a trivial distribution story (install your cmti and mld files), and a consistant and quick way for your users to access the documentation locally (namely odig doc yourpackage) using the stylesheet they wish.

[chetmurthy]

.mld files would be lovely, but I think that the ability to publish in RST format to readthedocs.io is .... attractive. Also, this is for camlp5, and there's a -ton- of real documentation that can't really fit into MLI files: I mean, imagine shoe-horning the entire Ocaml manual into MLI files ... that'd be difficult and ugly. Notwithstanding, I'd like to have the API documentation more closely-integrated with the manual, hence my question (since I'd read that owl's doc is in sphinx, but they use odoc for API docs.)

[jzstark]

You may find this repo helpful: https://github.com/owlbarn/owl_guide. Though currently the package reference uses odoc.

[dbuenzli]

Also, this is for camlp5, and there's a -ton- of real documentation that can't really fit into MLI files

That's what .mld files are for... Here's an example of a manual and its source.

imagine shoe-horning the entire Ocaml manual into MLI files

Not into .mli files but .mld ones certainly, with one .mld file per chapter. You basically have the power of markdown but with decent and checked xref capabilities.

The support is not perfect yet, but could maybe expand on what you think is missing ? At some point I was trying to convince @mseri for owl to switch to .mld files but a blocker was this.

readthedocs.io is .... attractive

I don't like the ads... But more imporantly chasing the web to track the documentation of the various components I may be using and each having its own particular presentation is, as far as I'm concerned, a bad user experience .

.mld files solve that problem and moreover in a way that is trivial for the producer (just install your .mld files, odig will figure out).

[chetmurthy]

Daniel,

Thank you, I now understand that I can use .mld files for writing documentation, and that's excellent. Nevertheless, for -delivering- documentation, there are still good things about RST, and about readthedocs.io. One can dislike the ads, or whatever, and still recognize that it's a good way to make documentation available to the masses.

[dbuenzli]

and still recognize that it's a good way to make documentation available to the masses.

I don't but... it's your project :-)

[chetmurthy]

It's all good, man. Your code speaks for itself grin. Also though, at some point, once I get all this code that is in-progress, out the door, maybe I should look at writing an RST backend for odoc. I cant' say I have any ideas on this: I'm still getting used to the idea of writing -documentation-, HAHAHAHA! [ok, ok, I know it's important to do, but ..... it's not something I've ever done much of in my career .... as they say at Google, "sometimes, the source code is the best documentation ..." (and they're wrong to say that, WRONG!)]

[dbuenzli]

I'm still getting used to the idea of writing -documentation-

I stopped worrying about writing documentation the day I started using it as a design tool: if you are unable to explain your system design, functions, types, modules using simple plain natural language, then it's likely you have not reached the design fix point yet.

[ryanrhymes]

Very insightful discussions :+1: