OCaml reference manual and general release process #93
Comments
|
Hi @Octachron! Thanks for opening the issue to get the conversation going. My understanding is that we'd like the OCaml manual to be integrated with the new website (integrated here means that the design is consistent with the rest of the website). Based on this requirement alone, the simplest solution I see would be to keep producing the manual in HTML and adapt the CSS to match the new design. So from a compiler maintainer point of view, the process would look like:
Does this make sense? Am I missing something? |
|
Copying the html manual is essentially the process that we are using with the old version, so it makes sense to me. I don't think that there are any specific requirements for the manual. Adapting the CSS might be the most time intensive part. I wonder if at some point we should merge the standard library API documentation with the opam-wide package documentation, but this is probably more of a medium term goal. |
I don't think this will be too difficult. I think we can re-use most of the styling of the package documentation. Looking at the HTML output of the manual, I can see a few things that might make the integration tedious:
Is there anything that can be done for the above? I'm guessing not, since the manual is produced from LaTex? |
|
An alternative would be to have the OCaml manual in the ocamldoc syntax. When releasing a new version on opam, the documentation pipeline will catch that and compile the HTML and other files that we need to render the documentation (navbar in particular). This is certainly a bit more time-consuming, but we would have a single infrastructure for the opam packages and the OCaml manual, and this would remove one step from the compiler release process. |
|
The manual already has a post-processing part to restructure the html (in order to achieve a faster iteration speed compared to patching hevea). Extracting the body and the navbar should not add a lot of complexity. Rendering with ocamldoc syntax is straightforward for the API documentation, but the core manual uses too much latex to make that path a short term option. It might be doable in the longer term however: it is not really that clear how many latex features are strictly needed. |
This would be useful to scope out to get a sample of what gaps there are in odoc-flavoured-ocamldoc syntax - e.g. we discussed missing images and tables in our meeting yesterday. |
That's great news! The ideal assets to include in ood on our side would be something similar to the documentation pipeline's output. The HTML that is embedded in the page looks like this: And we use a JSON file like this to produce the navigation bar: Would it make sense to post-process the manual to produce something like this? |
|
That sounds doable in principle. |
|
How would you recommend we get started on this? If you point me to the code that does this post-processing, I can look into making the necessary changes and follow up with a PR if that can help. |
|
The post-processing source file are here: https://github.com/ocaml/ocaml/tree/trunk/manual/src/html_processing . The generation itself is done with |
ghost
mentioned this issue
|
Fixed by #2150 |
Currently, the OCaml manual is hosted on
ocaml.org, and I update the manual version along with the description of the new release around release time. I am not sure what should be the process for theocaml.orgv3?The text was updated successfully, but these errors were encountered: