[was: generation of ocamldoc HTML documentation for libs (via cdbs)] OCaml policy for documentation
Hello,
On 26-08-2007, Stefano Zacchiroli <zack@debian.org> wrote:
>
> --C7zPtVaVf+AK4Oqc
> Content-Type: text/plain; charset=us-ascii
> Content-Disposition: inline
> Content-Transfer-Encoding: quoted-printable
>
> On Sun, Aug 26, 2007 at 12:46:46PM +0000, Sylvain Le Gall wrote:
>> I am for the first solution, which will make every DD aware of the
>> need of ocamldoc documentation ! (or switch it off ;-)
>
> Fair enough, then my question is: what about making mandatory per our
> policy to generate ocamldoc documentation?
>
I agree on integrating it to the policy. But maybe we should also
integrate things like:
* every cmi file MUST come with a human readable mli file
* there MUST be at least one mli file per -dev package
* at least one ocamldoc generated HTML file MUST be placed in
/usr/share/doc/PACKAGE/html/ocamldoc (if upstream generated, using
another mean, a link must be made between this location and the
generated path location
* a set of manpage MUST be generated out of the same source of ocamldoc
HTML file
Today, this are only SHOULD clause in our policy. I think the first 3
items are quite common and should cause no problem for most of ocaml
packages. The manpage stuff is more problematic, but should be a good
step (if possible).
> And also remember the potential benefits of centralizing such generation
> via CDBS, we can for example in the future implement an OCaml API
> documentation registry and provide an HTML (or whatever) index of all
> installed modules. All this can be implemented in a single place if all
> packages generate documentation using a single mechanism ...
>
There is a comment about this in our policy, concerning the use of
"-dump" and "-load" in ocamldoc. We could use this file to only ship
ocamldoc dump file and register generated documentation
(HTML/manpage/info) on the host system, depending on user system
configuration (only HTML or HTML + man...). This is not very
complicated, but need to be done by someone ;-)
Regards,
Sylvain Le Gall
Reply to: