From f04be44adcf8a42f870d2bf99e8cba17b884bb00 Mon Sep 17 00:00:00 2001
From: Etienne Millon <me@emillon.org>
Date: Tue, 5 Mar 2024 16:34:34 +0100
Subject: [PATCH] doc: remove dune:action directive (#10152)

* doc: use describe instead of dune:action

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

* Remove actions from dunedomain

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

---------

Signed-off-by: Etienne Millon <me@emillon.org>
---
 doc/exts/sphinx_dunedomain.py                 | 35 +------------------
 doc/reference/actions/bash.rst                |  3 +-
 doc/reference/actions/cat.rst                 |  3 +-
 doc/reference/actions/chdir.rst               |  3 +-
 doc/reference/actions/cmp.rst                 |  3 +-
 doc/reference/actions/concurrent.rst          |  3 +-
 doc/reference/actions/copy#.rst               |  3 +-
 doc/reference/actions/copy.rst                |  3 +-
 doc/reference/actions/diff.rst                |  3 +-
 doc/reference/actions/diffq.rst               |  3 +-
 doc/reference/actions/dynamic-run.rst         |  3 +-
 doc/reference/actions/echo.rst                |  3 +-
 doc/reference/actions/ignore-outputs.rst      |  3 +-
 doc/reference/actions/no-infer.rst            |  3 +-
 doc/reference/actions/pipe-outputs.rst        |  3 +-
 doc/reference/actions/progn.rst               |  3 +-
 doc/reference/actions/run.rst                 |  3 +-
 doc/reference/actions/setenv.rst              |  3 +-
 doc/reference/actions/system.rst              |  3 +-
 .../actions/with-accepted-exit-codes.rst      |  3 +-
 doc/reference/actions/with-outputs-to.rst     |  3 +-
 doc/reference/actions/with-stdin-from.rst     |  3 +-
 doc/reference/actions/write-file.rst          |  3 +-
 23 files changed, 23 insertions(+), 78 deletions(-)

diff --git a/doc/exts/sphinx_dunedomain.py b/doc/exts/sphinx_dunedomain.py
index 00af6e5e4f6..8e16571c2ca 100644
--- a/doc/exts/sphinx_dunedomain.py
+++ b/doc/exts/sphinx_dunedomain.py
@@ -134,38 +134,15 @@ def add_target_and_index(self, name_cls, sig, signode):
         domain.add_field(path, sig)
 
 
-class ActionDirective(ObjectDescription):
-    """
-    The action directive.
-    """
-
-    option_spec = {
-        "param": directives.unchanged_required,
-    }
-
-    def handle_signature(self, sig, signode):
-        param = self.options.get("param", "...")
-        text = f"({sig} {param})"
-        signode += addnodes.desc_name(text=text)
-        return sig
-
-    def add_target_and_index(self, name_cls, sig, signode):
-        signode["ids"].append(f"action-{sig}")
-        domain = self.env.get_domain("dune")
-        domain.add_action(name_cls)
-
-
 class DuneDomain(Domain):
     name = "dune"
 
     directives = {
         "stanza": StanzaDirective,
         "field": FieldDirective,
-        "action": ActionDirective,
     }
     indices = {StanzaIndex, FieldIndex}
     initial_data = {"stanzas": [], "fields": []}
-    object_types = {"action": ObjType("action")}
 
     def get_full_qualified_name(self, node):
         return f"stanza.{node.arguments[0]}"
@@ -173,14 +150,8 @@ def get_full_qualified_name(self, node):
     def get_stanzas(self):
         return self.data["stanzas"]
 
-    def get_actions(self):
-        return [
-            (f"action.{name}", name, "action", docname, f"action-{name}", 0)
-            for name, docname in self.actions.items()
-        ]
-
     def get_objects(self):
-        return self.get_stanzas() + self.get_actions()
+        return self.get_stanzas()
 
     def add_stanza(self, signature):
         name = f"stanza.{signature}"
@@ -200,12 +171,8 @@ def add_field(self, path, field):
         typ = f"Field in {pretty_path}"
         self.data["fields"].append((name, field, typ, self.env.docname, anchor))
 
-    def add_action(self, name):
-        self.actions[name] = self.env.docname
-
     def setup(self):
         super().setup()
-        self.actions = {}
         self.env.current_path = []
 
     def find_object(self, typ, name):
diff --git a/doc/reference/actions/bash.rst b/doc/reference/actions/bash.rst
index 1d007e23c36..e582c192cbb 100644
--- a/doc/reference/actions/bash.rst
+++ b/doc/reference/actions/bash.rst
@@ -3,8 +3,7 @@ bash
 
 .. highlight:: dune
 
-.. dune:action:: bash
-   :param: <cmd>
+.. describe:: (bash <cmd>)
 
    Execute a command using ``/bin/bash``. This is obviously not very portable.
 
diff --git a/doc/reference/actions/cat.rst b/doc/reference/actions/cat.rst
index b8e06e7d1b6..f2443f0a277 100644
--- a/doc/reference/actions/cat.rst
+++ b/doc/reference/actions/cat.rst
@@ -3,8 +3,7 @@ cat
 
 .. highlight:: dune
 
-.. dune:action:: cat
-   :param: <file> ...
+.. describe:: (cat <file> ...)
 
    Sequentially print the contents of files to stdout.
 
diff --git a/doc/reference/actions/chdir.rst b/doc/reference/actions/chdir.rst
index 1d8b5d3376c..df5aeaeb7e6 100644
--- a/doc/reference/actions/chdir.rst
+++ b/doc/reference/actions/chdir.rst
@@ -3,8 +3,7 @@ chdir
 
 .. highlight:: dune
 
-.. dune:action:: chdir
-   :param: <dir> <DSL>
+.. describe:: (chdir <dir> <DSL>)
 
    Run an action in a different directory.
 
diff --git a/doc/reference/actions/cmp.rst b/doc/reference/actions/cmp.rst
index 3ef4f8216c7..5e154c7cc00 100644
--- a/doc/reference/actions/cmp.rst
+++ b/doc/reference/actions/cmp.rst
@@ -3,8 +3,7 @@ cmp
 
 .. highlight:: dune
 
-.. dune:action:: cmp
-   :param: <file1> <file2>
+.. describe:: (cmp <file1> <file2>)
 
    ``(cmp <file1> <file2>)`` is similar to ``(run cmp <file1> <file2>)`` but
    allows promotion. See :doc:`/concepts/promotion` for more details.
diff --git a/doc/reference/actions/concurrent.rst b/doc/reference/actions/concurrent.rst
index 4a8f7ba4fc7..0f0a4f5ab17 100644
--- a/doc/reference/actions/concurrent.rst
+++ b/doc/reference/actions/concurrent.rst
@@ -3,8 +3,7 @@ concurrent
 
 .. highlight:: dune
 
-.. dune:action:: concurrent
-   :param: <DSL>...
+.. describe:: (concurrent <DSL> ...)
 
    Execute several commands concurrently and collect all resulting errors, if any.
 
diff --git a/doc/reference/actions/copy#.rst b/doc/reference/actions/copy#.rst
index c571ecc4415..39f80e34df8 100644
--- a/doc/reference/actions/copy#.rst
+++ b/doc/reference/actions/copy#.rst
@@ -3,8 +3,7 @@ copy#
 
 .. highlight:: dune
 
-.. dune:action:: copy#
-   :param: <src> <dst>
+.. describe:: (copy# <src> <dst>)
 
    Copy a file and add a line directive at the beginning.
 
diff --git a/doc/reference/actions/copy.rst b/doc/reference/actions/copy.rst
index e340d4a2e3f..e7d8c5b458e 100644
--- a/doc/reference/actions/copy.rst
+++ b/doc/reference/actions/copy.rst
@@ -3,8 +3,7 @@ copy
 
 .. highlight:: dune
 
-.. dune:action:: copy
-   :param: <src> <dst>
+.. describe:: (copy <src> <dst>)
 
    Copy a file. If these files are OCaml sources, you should follow the
    ``module_name.xxx.ml`` :ref:`naming convention <merlin-filenames>` to
diff --git a/doc/reference/actions/diff.rst b/doc/reference/actions/diff.rst
index 23400ccb19c..974d9445ab5 100644
--- a/doc/reference/actions/diff.rst
+++ b/doc/reference/actions/diff.rst
@@ -3,8 +3,7 @@ diff
 
 .. highlight:: dune
 
-.. dune:action:: diff
-   :param: <file1> <file2>
+.. describe:: (diff <file1> <file2>)
 
    ``(diff <file1> <file2>)`` is similar to ``(run diff <file1> <file2>)`` but
    is better and allows promotion. See :doc:`/concepts/promotion` for more
diff --git a/doc/reference/actions/diffq.rst b/doc/reference/actions/diffq.rst
index 04f10dbb566..bfe77291fa5 100644
--- a/doc/reference/actions/diffq.rst
+++ b/doc/reference/actions/diffq.rst
@@ -3,8 +3,7 @@ diff?
 
 .. highlight:: dune
 
-.. dune:action:: diff?
-   :param: <file1> <file2>
+.. describe:: (diff? <file1> <file2>)
 
    ``(diff? <file1> <file2>)`` is similar to ``(diff <file1> <file2>)`` except
    that ``<file2>`` should be produced by a part of the same action rather than
diff --git a/doc/reference/actions/dynamic-run.rst b/doc/reference/actions/dynamic-run.rst
index 17c0f3994bd..6e83343c990 100644
--- a/doc/reference/actions/dynamic-run.rst
+++ b/doc/reference/actions/dynamic-run.rst
@@ -3,8 +3,7 @@ dynamic-run
 
 .. highlight:: dune
 
-.. dune:action:: dynamic-run
-   :param: <prog> <args>
+.. describe:: (dynamic-run <prog> <args>)
 
    Execute a program that was linked against the ``dune-action-plugin`` library.
    ``<prog>`` is resolved in the same way as in :doc:`run`.
diff --git a/doc/reference/actions/echo.rst b/doc/reference/actions/echo.rst
index b9018b08160..fc50b13b0fa 100644
--- a/doc/reference/actions/echo.rst
+++ b/doc/reference/actions/echo.rst
@@ -3,8 +3,7 @@ echo
 
 .. highlight:: dune
 
-.. dune:action:: echo
-   :param: <string>
+.. describe:: (echo <string>)
 
    Output a string on ``stdout``.
 
diff --git a/doc/reference/actions/ignore-outputs.rst b/doc/reference/actions/ignore-outputs.rst
index 0d22a59eb80..940eeb702a9 100644
--- a/doc/reference/actions/ignore-outputs.rst
+++ b/doc/reference/actions/ignore-outputs.rst
@@ -3,8 +3,7 @@ ignore-<outputs>
 
 .. highlight:: dune
 
-.. dune:action:: ignore-<outputs>
-   :param: <DSL>
+.. describe:: (ignore-<outputs> <DSL>)
 
    Ignore the output, where ``<outputs>`` is one of: ``stdout``, ``stderr``, or
    ``outputs``.
diff --git a/doc/reference/actions/no-infer.rst b/doc/reference/actions/no-infer.rst
index 796c0069680..c8a0d7f1ff0 100644
--- a/doc/reference/actions/no-infer.rst
+++ b/doc/reference/actions/no-infer.rst
@@ -3,8 +3,7 @@ no-infer
 
 .. highlight:: dune
 
-.. dune:action:: no-infer
-   :param: <DSL>
+.. describe:: (no-infer <DSL>)
 
    Perform an action without inference of dependencies and targets. This is
    useful if you are generating dependencies in a way that Dune doesn't know
diff --git a/doc/reference/actions/pipe-outputs.rst b/doc/reference/actions/pipe-outputs.rst
index 60a1ccf1e25..b5cbd0859f9 100644
--- a/doc/reference/actions/pipe-outputs.rst
+++ b/doc/reference/actions/pipe-outputs.rst
@@ -3,8 +3,7 @@ pipe-<outputs>
 
 .. highlight:: dune
 
-.. dune:action:: pipe-<outputs>
-   :param: <DSL> <DSL> <DSL>...
+.. describe:: (pipe-<outputs> <DSL> <DSL> <DSL>...)
 
    .. versionadded:: 2.7
 
diff --git a/doc/reference/actions/progn.rst b/doc/reference/actions/progn.rst
index 307b13bff9a..caae33b934d 100644
--- a/doc/reference/actions/progn.rst
+++ b/doc/reference/actions/progn.rst
@@ -3,8 +3,7 @@ progn
 
 .. highlight:: dune
 
-.. dune:action:: progn
-   :param: <DSL>...
+.. describe:: (progn <DSL> ...)
 
    Execute several commands in sequence.
 
diff --git a/doc/reference/actions/run.rst b/doc/reference/actions/run.rst
index 6365f14d914..60117dd2cba 100644
--- a/doc/reference/actions/run.rst
+++ b/doc/reference/actions/run.rst
@@ -3,8 +3,7 @@ run
 
 .. highlight:: dune
 
-.. dune:action:: run
-   :param: <prog> <args>
+.. describe:: (run <prog> <args>)
 
    Execute a program. ``<prog>`` is resolved locally if it is available in the
    current workspace, otherwise it is resolved using the ``PATH``.
diff --git a/doc/reference/actions/setenv.rst b/doc/reference/actions/setenv.rst
index 58802d0e398..c78eb77bb7c 100644
--- a/doc/reference/actions/setenv.rst
+++ b/doc/reference/actions/setenv.rst
@@ -3,8 +3,7 @@ setenv
 
 .. highlight:: dune
 
-.. dune:action:: setenv
-   :param: <var> <value> <DSL>
+.. describe:: (setenv <var> <value> <DSL>)
 
    Run an action with an environment variable set.
 
diff --git a/doc/reference/actions/system.rst b/doc/reference/actions/system.rst
index d4ced8b70d3..eda869634b8 100644
--- a/doc/reference/actions/system.rst
+++ b/doc/reference/actions/system.rst
@@ -3,8 +3,7 @@ system
 
 .. highlight:: dune
 
-.. dune:action:: system
-   :param: <cmd>
+.. describe:: (system <cmd>)
 
    Execute a command using the system shell: ``sh`` on Unix and ``cmd`` on Windows.
 
diff --git a/doc/reference/actions/with-accepted-exit-codes.rst b/doc/reference/actions/with-accepted-exit-codes.rst
index a01e6f4a957..799e33a6e79 100644
--- a/doc/reference/actions/with-accepted-exit-codes.rst
+++ b/doc/reference/actions/with-accepted-exit-codes.rst
@@ -3,8 +3,7 @@ with-accepted-exit-codes
 
 .. highlight:: dune
 
-.. dune:action:: with-accepted-exit-codes
-   :param: <pred> <DSL>
+.. describe:: (with-accepted-exit-codes <pred> <DSL>)
 
    .. versionadded:: 2.0
 
diff --git a/doc/reference/actions/with-outputs-to.rst b/doc/reference/actions/with-outputs-to.rst
index 0f0faa1cb57..e3470eb091e 100644
--- a/doc/reference/actions/with-outputs-to.rst
+++ b/doc/reference/actions/with-outputs-to.rst
@@ -3,8 +3,7 @@ with-<outputs>-to
 
 .. highlight:: dune
 
-.. dune:action:: with-<outputs>-to
-   :param: <file> <DSL>
+.. describe:: (with-<outputs>-to <file> <DSL>)
 
    Redirect the output to a file, where ``<outputs>`` is one of: ``stdout``,
    ``stderr`` or ``outputs`` (for both ``stdout`` and ``stderr``).
diff --git a/doc/reference/actions/with-stdin-from.rst b/doc/reference/actions/with-stdin-from.rst
index 2d0aeb014fa..123db0d7d3c 100644
--- a/doc/reference/actions/with-stdin-from.rst
+++ b/doc/reference/actions/with-stdin-from.rst
@@ -3,8 +3,7 @@ with-stdin-from
 
 .. highlight:: dune
 
-.. dune:action:: with-stdin-from
-   :param: <file> <DSL>
+.. describe:: (with-stdin-from <file> <DSL>)
 
    Redirect the input from a file.
 
diff --git a/doc/reference/actions/write-file.rst b/doc/reference/actions/write-file.rst
index 9e94de32372..0ab8b93f95f 100644
--- a/doc/reference/actions/write-file.rst
+++ b/doc/reference/actions/write-file.rst
@@ -3,8 +3,7 @@ write-file
 
 .. highlight:: dune
 
-.. dune:action:: write-file
-   :param: <file> <string>
+.. describe:: (write-file <file> <string>)
 
    Writes ``<string>`` to ``<file>``.