From d2484e3d3dbe6bfe4305fdfc9749c3b70131bff3 Mon Sep 17 00:00:00 2001
From: Etienne Millon <me@emillon.org>
Date: Wed, 17 Jul 2024 11:08:42 +0200
Subject: [PATCH] doc: use describe in alias.rst (#10720)

Signed-off-by: Etienne Millon <me@emillon.org>
---
 doc/reference/dune/alias.rst | 87 +++++++++++++++++++++---------------
 1 file changed, 51 insertions(+), 36 deletions(-)

diff --git a/doc/reference/dune/alias.rst b/doc/reference/dune/alias.rst
index eee291a54b3..dd3877850a2 100644
--- a/doc/reference/dune/alias.rst
+++ b/doc/reference/dune/alias.rst
@@ -1,55 +1,70 @@
+.. highlight:: dune
+
 alias
 -----
 
-The ``alias`` stanza adds dependencies to an alias or specifies an action to run
-to construct the alias.
+.. describe:: (alias ...)
+
+   Add dependencies to an alias.
+
+   Aliases do not need to be explicitly created, adding to a new name will
+   "create" an alias.
+   An alias with name ``x`` can be built by running ``dune build @x``.
+   See :doc:`/reference/aliases`.
+
+   The common use of the ``alias`` stanza is make an alias depend on other ones::
+
+       (alias
+        (name runtest)
+        (deps
+         (alias test-unit)
+         (alias test-integration)))
+
+   .. warning::
+
+      In previous versions of the dune language, it was also possible to specify
+      an action to run to construct the alias. Please use a :doc:`rule` stanza
+      with the ``alias`` field instead.
+
+   This stanza supports the following fields:
+
+   .. describe:: (name <name>)
+
+      An alias name.
 
-The syntax is as follows:
+      Attaching dependencies to ``(name x)`` will ensure they are built by
+      ``dune build @x``.
 
-.. code:: dune
+      This field is required.
 
-    (alias
-     (name    <alias-name>)
-     (deps    <deps-conf list>)
-     <optional-fields>)
+   .. describe:: (deps <deps-conf list)
 
-``<name>`` is an alias name such as ``runtest``.
+      Specifies the dependencies of the alias.
 
-.. _alias-fields:
+      See :doc:`/concepts/dependency-spec` for more details.
 
-``<deps-conf list>`` specifies the dependencies of the alias. See
-:doc:`/concepts/dependency-spec` for more details.
+      This field is required.
 
-``<optional-fields>`` are:
+   .. describe:: (enabled_if <blang expression>)
 
-- ``<action>``, an action for constructing the alias. See
-  :doc:`/reference/actions/index` for more details. Note that this is removed
-  in Dune 2.0, so users must port their code to use the ``rule`` stanza with
-  the ``alias`` field instead.
+      Specifies the Boolean condition that must be true for the tests to run.
 
-- ``(package <name>)`` indicates that this alias stanza is part of package
-  ``<name>`` and should be filtered out if ``<name>`` is filtered out from the
-  command line, either with ``--only-packages <pkgs>`` or ``-p <pkgs>``.
+      The condition is specified using the :doc:`/reference/boolean-language`, and
+      the field allows for :doc:`/concepts/variables` to appear in the expressions.
 
-- ``(locks (<lock-names>))`` specifies that the action must be run while holding
-  the following locks. See :doc:`/concepts/locks` for more details.
+   .. describe:: (action <action>)
 
-- ``(enabled_if <blang expression>)`` specifies the Boolean condition that must
-  be true for the tests to run. The condition is specified using the
-  :doc:`/reference/boolean-language`, and the field allows for
-  :doc:`/concepts/variables` to appear in the expressions.
+      .. versionremoved :: 2.0 use :doc:`rule` with the ``alias`` field instead.
 
-The typical use of the ``alias`` stanza is to define tests:
+      An :doc:`action </reference/actions/index>` for constructing the alias.
 
-.. code:: dune
+   .. describe:: (package <name>)
 
-    (rule
-     (alias   runtest)
-     (action (run %{exe:my-test-program.exe} blah)))
+      Indicates that this alias stanza is part of package ``<name>`` and should be
+      filtered out if ``<name>`` is filtered out from the command line, either with
+      ``--only-packages <pkgs>`` or ``-p <pkgs>``.
 
-See the section about :ref:`running-tests` for details.
+   .. describe:: (locks (<lock-names>))
 
-Please note: if your project contains several packages, and you run the tests
-from the opam file using a ``build-test`` field, all your ``runtest`` alias
-stanzas should have a ``(package ...)`` field in order to partition the set of
-tests.
+      Specifies that the action must be run while holding the following locks. See
+      :doc:`/concepts/locks` for more details.