mirage
Include README in cohttp documentation
It now contains plenty of useful examples and explanations which are missing from the library docs.
Hi @mseri ! I'm fairly new to OCaml as I'm currently learning it at school, however I would love to work on this issue as well as on some other documentation ones. It could definitely be a great way to get acquainted with this awesome project and start contributing to it!
If I understand this correctly, we should incorporate the current doc from the README in bits and pieces throughout the code as, from what I gather, the doc is generated using ocamldoc?
Hi, thanks for the interest!
I had in mind something similar to https://github.com/mirage/ocaml-rpc/blob/master/docs/dune
In this case, instead, I think we should create an index.mld manually which links to the various libraries with a bit of preamble (explaining what each of them is). And then, for example, use md2mld to generate an extra README.mld or introduction.mld page (or viceversa, write the mld page and generate the README from it, but I think it is more complicated).
The ocamldoc syntax is explained here: https://ocaml.org/manual/ocamldoc.html
It may be that md2mld will need to be extended to properly transform cohttp README which is quite extensive.
Of course, if you have a different suggestion I am open for discussion or for reviewing a PR :)