Add a doc entry for setting up an OxCaml project with dune pkg

[Sudha247]

Closes #11652

Adds a tutorial for setting up an OxCaml project with Dune package management.

I contemplated where this should go, and thought this might be a good place, after all. It shows (1) how to setup an OxCaml project, (2) servers as a live example of the previous two tutorials.

#12111 is a more comprehensive tutorial about parametric libraries and OxCaml, but it doesn't specifically cover the topic of Dune package management with OxCaml. I recently ported an OxCaml project to build with Dune package management and the configuration was not as straightforward as I expected, and thought a tutorial on this topic might be useful.

This takes some material from https://github.com/gridbugs/hello-oxcaml (thanks @gridbugs!).

[Alizter]

Here are some screenshots:

I think having these drop-down code excerpts is kind of pointless. Perhaps it would be better just to have the code inline like we do elsewhere in the docs.

[Alizter]

The main title doesn't need to say Example: probably.

[shonfeder]

Glad to have this included!

[Alizter]

At some point these how-to's turned into markdown rather than being rst documents which is slightly confusing. In rst we have syntax highlighting for dune files etc. Does anybody remember why markdown was chosen for these?

I would suggest writing this tutorial in rst, not only for consistency, but because it will play better with cross-linking that we have elsewhere in the docs.

[Sudha247]

I would suggest writing this tutorial in rst, not only for consistency, but because it will play better with cross-linking that we have elsewhere in the docs.

I'm not opposed to doing this, but wouldn't be weird if only one of the dune-package-management entries is in rst, while others are in markdown?

[Alizter]

Ideally they should be all in rst, but would blow this PR out of scope. If you think it would be too much work to do in this PR, let's instead create an issue so that we remember to do it eventually. I won't block on this point.

[Leonidas-from-XIV]

Ah, I dug a bit around and it is because of this PR by @emillon where he notes:

• it maps fully to reST
• it's more contributor friendly
• editor tooling is better
• it alleviates some vendor lock-in (since we're likely to migrate to ocaml.org at some point, and it's more likely to use a variant of md than sphinx support odoc syntax)

Which all sound like pretty decent points.

[Leonidas-from-XIV]

This path is probably optional.

[Alizter]

We also have a macros for the latest dune lang version which might be sensible to use.

[shonfeder]

Suggested change

	[OxCaml](https://oxcaml.org/) project. OxCaml is a compiler branch with fast
	moving set of extensions to OCaml. Some tweaks are required to set up a project
	[OxCaml](https://oxcaml.org/) project. OxCaml is a compiler branch with a fast
	moving set of extensions to OCaml. Some tweaks are required to set up a project

[shonfeder]

Suggested change

	(repositories :standard oxcaml))
	(pins ocamlbuild)
	(repositories :standard oxcaml))

[shonfeder]

Apparently the pins in a workspace are just declarations of names (unlike pin in a dune-project, which work differently for some reason?), and to get the pin to actually pin you have also declare it for every lock_dir

[Sudha247]

I've addressed all the comments. I've also made the configuration of dev tools point to the how-to guide so we have a single source of information. However, this tutorial is now hitting #12839 and #12851. But there's nothing to change in the tutorial as such.

[shonfeder]

Perhaps the solution for the oxcaml-side is just to undo (my suggestion of) using the lockless package management until that is fixed? We could create a TODO on the docs to simplify, and cross link from #12851, which would allow us to close this with correct information, and track the need to update it when the latter is fixed.

Does this sound like an OK way forward, @Sudha247 ?

[Sudha247]

That sounds good to me. I will undo the autolocking part, write a TODO in the docs to fix this, and note it down in #12851.