doc: add a "developing with dune" tutorial (#10711)

This adds a new tutorial (our first one!) about common interactions with
dune, how to structure a project, using diffing and promotion, etc. The
goal is to cover the 20% simple parts of dune that will be used 80% of
the time.

I relied heavily on https://diataxis.fr/ for that, in particular I don't
consider that this is finished work, just that it's now just complete
enough to be integrated in main. I did some user testing on the first
half, and I consider that the first half is pretty OK, while the second
part (starting from C stubs) will need more work to be usable, but I'll
continue improving that in main with more user testing.

A technical aspect of that PR is that I decided to go with myst
(markdown parser for sphinx) - see the syntax guide. I don't want to
make it a policy, but I think for new documents it makes sense to use
something like that, because:

- 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)

The page is marked as orphan and WIP for now since it's not meant for
end users yet.

Signed-off-by: Etienne Millon <me@emillon.org>

doc/conf.py

@@ -42,8 +42,11 @@
 extensions = [
     'sphinx_copybutton',
     'sphinx_design',
+    'myst_parser',
 ]
 
+myst_enable_extensions = ["colon_fence"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -71,7 +74,14 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    '_build',
+    'Thumbs.db',
+    '.DS_Store',
+    'dev',
+    'papers',
+    'changes',
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'friendly'

doc/dune

@@ -32,3 +32,5 @@
 
 (documentation
  (package dune))
+
+(data_only_dirs tutorials)

doc/overview.rst

@@ -149,6 +149,13 @@ Terminology
      :ref:`dune-subst` for development versions and dune-release_ for
      releases.
 
+   stanza
+     A fragment of a file interpreted by Dune, that will appear as a
+     s-expression at the top-level of a file. For example, the
+     :doc:`/reference/dune/library` stanza describes a library. This can be
+     either a generic term ("the library stanza") or it can refer to a
+     particular instance in a file ("the executable stanza in ``bin/dune``").
+
 Project Layout
 ==============
 

doc/requirements.txt

@@ -2,3 +2,4 @@ sphinx >= 6
 furo
 sphinx-copybutton >= 0.5.0
 sphinx-design
+myst-parser

doc/tutorials/developing-with-dune/conclusion.md

@@ -0,0 +1,19 @@
+Conclusion
+==========
+
+This tutorial has covered the parts of Dune that users are the most likely to
+interact with:
+
+- the {doc}`/reference/dune/executable`, {doc}`/reference/dune/library`, and
+  {doc}`/reference/dune/test` stanzas;
+- how to use {doc}`cram tests</reference/cram>` and the workflow of
+  {doc}`promotion </concepts/promotion>`;
+- bindings to C code using {doc}`foreign stubs </reference/foreign-stubs>`;
+- using a ppx deriver.
+
+## Where to go from here
+
+You might be interested in:
+
+- our {doc}`how-to guides </howto/index>` to apply this to your projects;
+- various {doc}`explanations </explanation/index>` about how Dune works.