Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OCaml reference manual and general release process #93

Closed
Octachron opened this issue Sep 10, 2021 · 11 comments
Closed

OCaml reference manual and general release process #93

Octachron opened this issue Sep 10, 2021 · 11 comments

Comments

@Octachron
Copy link
Member

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 the ocaml.org v3?

@tmattio
Copy link
Collaborator

tmattio commented Sep 10, 2021

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).
Have there been any other requirements discussed?

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.
The HTML can then be embedded in the site's layout by the server. To allow the server to do this, the HTML output of the manual can be copied (in the form of a PR) to ood when a new version is released.

So from a compiler maintainer point of view, the process would look like:

  • Update the version and the description when releasing
  • Produce the HTML output of the manual
  • Copy it in a directory in ood and open a PR

Does this make sense? Am I missing something?

@Octachron
Copy link
Member Author

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.

@tmattio
Copy link
Collaborator

tmattio commented Sep 10, 2021

Adapting the CSS might be the most time intensive part.

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:

  • The HTML contains the whole document. If we want to integrate it into the new website, we're only interested in the <body> content.
  • The sidebar is integrated into the HTML directly, which does not give a lot of flexibility on how we want to render it.

Is there anything that can be done for the above? I'm guessing not, since the manual is produced from LaTex?

@tmattio
Copy link
Collaborator

tmattio commented Sep 10, 2021

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.

@Octachron
Copy link
Member Author

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.

@jonludlam
Copy link
Member

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.

@tmattio
Copy link
Collaborator

tmattio commented Sep 10, 2021

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.

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?

@Octachron
Copy link
Member Author

That sounds doable in principle.

@tmattio
Copy link
Collaborator

tmattio commented Sep 10, 2021

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.

@Octachron
Copy link
Member Author

The post-processing source file are here: https://github.com/ocaml/ocaml/tree/trunk/manual/src/html_processing . The generation itself is done with make web from the manual directory. If you have the time to have a look, it would be great. Otherwise, I will try to have a look later in the 4.14 cycle.

@cuihtlauac
Copy link
Collaborator

Fixed by #2150

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

No branches or pull requests

4 participants