From 633256c87e7603a7ff12b9b199ce37fbda376f63 Mon Sep 17 00:00:00 2001 From: Etienne Millon Date: Wed, 6 Mar 2024 14:22:20 +0100 Subject: [PATCH] doc: remove dune:stanza directive (#10219) * remove dune:stanza uses Signed-off-by: Etienne Millon * remove dunedomain Signed-off-by: Etienne Millon --------- Signed-off-by: Etienne Millon --- doc/conf.py | 1 - doc/exts/sphinx_dunedomain.py | 124 ------------------ .../accept_alternative_dune_file_name.rst | 2 +- doc/reference/files/dune-project/cram.rst | 3 +- doc/reference/files/dune-project/dialect.rst | 2 +- .../executables_implicit_empty_intf.rst | 2 +- .../expand_aliases_in_sandbox.rst | 2 +- .../files/dune-project/explicit_js_mode.rst | 2 +- .../files/dune-project/formatting.rst | 2 +- .../dune-project/generate_opam_files.rst | 22 ++-- .../dune-project/implicit_transitive_deps.rst | 2 +- .../files/dune-project/map_workspace_root.rst | 3 +- doc/reference/files/dune-project/name.rst | 3 +- .../files/dune-project/opam_file_location.rst | 3 +- doc/reference/files/dune-project/package.rst | 2 +- doc/reference/files/dune-project/subst.rst | 3 +- .../use_standard_c_and_cxx_flags.rst | 2 +- doc/reference/files/dune-project/using.rst | 3 +- doc/reference/files/dune-project/version.rst | 3 +- doc/reference/files/dune-project/warnings.rst | 2 +- .../dune-project/wrapped_executables.rst | 3 +- doc/reference/files/dune/cram.rst | 2 +- 22 files changed, 27 insertions(+), 166 deletions(-) delete mode 100644 doc/exts/sphinx_dunedomain.py diff --git a/doc/conf.py b/doc/conf.py index c62c5e3f6c1..e7a44dc7d0a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -41,7 +41,6 @@ # ones. extensions = [ 'sphinx_copybutton', - 'sphinx_dunedomain', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/exts/sphinx_dunedomain.py b/doc/exts/sphinx_dunedomain.py deleted file mode 100644 index 8538f21ab21..00000000000 --- a/doc/exts/sphinx_dunedomain.py +++ /dev/null @@ -1,124 +0,0 @@ -from docutils.parsers.rst import directives -from docutils.nodes import literal, Text -from sphinx import addnodes -from sphinx.domains import Domain, Index, ObjType -from sphinx.directives import ObjectDescription -from collections import defaultdict -from sphinx.util.nodes import make_refnode - - -class StanzaIndex(Index): - name = "stanzaindex" - localname = "Stanzas" - - def generate(self, docnames=None): - content = defaultdict(list) - - stanzas = [ - (dispname, typ, docname, anchor) - for ( - name, - dispname, - typ, - docname, - anchor, - prio, - ) in self.domain.get_stanzas() - ] - - for dispname, typ, docname, anchor in stanzas: - content[dispname[0].lower()].append( - (dispname, 0, docname, anchor, docname, "", typ) - ) - - content = sorted(content.items()) - return content, True - - -class StanzaDirective(ObjectDescription): - """ - The stanza directive. - - It accepts a parameter named :param: which will be used as a placeholder. - For example: - - .. dune:stanza:: name - :param: - - gets expanded to (name ), but the following: - - .. dune:stanza:: env - - gets expanded to (env ...). - """ - - option_spec = { - "param": directives.unchanged_required, - } - - required_arguments = 1 - - def handle_signature(self, sig, signode): - param = self.options.get("param", "...") - text = f"({sig} {param})" - signode += addnodes.desc_name(text=text) - return sig - - def before_content(self, *args): - self.env.current_path.append(self.arguments[0]) - - def after_content(self, *args): - self.env.current_path.pop() - - def add_target_and_index(self, name_cls, sig, signode): - signode["ids"].append("stanza" + "-" + sig) - domain = self.env.get_domain("dune") - domain.add_stanza(sig) - - -class DuneDomain(Domain): - name = "dune" - - directives = { - "stanza": StanzaDirective, - } - indices = {StanzaIndex} - initial_data = {"stanzas": []} - - def get_full_qualified_name(self, node): - return f"stanza.{node.arguments[0]}" - - def get_stanzas(self): - return self.data["stanzas"] - - def get_objects(self): - return self.get_stanzas() - - def add_stanza(self, signature): - name = f"stanza.{signature}" - anchor = f"stanza-{signature}" - self.data["stanzas"].append( - (name, signature, "Stanza", self.env.docname, anchor, 0) - ) - - def setup(self): - super().setup() - self.env.current_path = [] - - def find_object(self, typ, name): - objects = self.get_objects() - matches = [ - (docname, anchor) - for _, obj_name, obj_typ, docname, anchor, _ in objects - if obj_name == name and obj_typ == typ - ] - assert matches, f"dune domain: found no {typ} named {name}" - assert len(matches) == 1, f"dune domain: found several {typ} named {name}" - return matches[0] - - -def setup(app): - app.add_domain(DuneDomain) - return { - "version": "0.1", - } diff --git a/doc/reference/files/dune-project/accept_alternative_dune_file_name.rst b/doc/reference/files/dune-project/accept_alternative_dune_file_name.rst index 4472e15f4b2..d59d115cd08 100644 --- a/doc/reference/files/dune-project/accept_alternative_dune_file_name.rst +++ b/doc/reference/files/dune-project/accept_alternative_dune_file_name.rst @@ -1,7 +1,7 @@ accept_alternative_dune_file_name --------------------------------- -.. dune:stanza:: accept_alternative_dune_file_name +.. describe:: (accept_alternative_dune_file_name ...) .. versionadded:: 3.0 diff --git a/doc/reference/files/dune-project/cram.rst b/doc/reference/files/dune-project/cram.rst index 9a2e30e81f6..65a0a14562f 100644 --- a/doc/reference/files/dune-project/cram.rst +++ b/doc/reference/files/dune-project/cram.rst @@ -1,8 +1,7 @@ cram ---- -.. dune:stanza:: cram - :param: +.. describe:: (cram ) Define whether Cram-style tests are enabled for the project. diff --git a/doc/reference/files/dune-project/dialect.rst b/doc/reference/files/dune-project/dialect.rst index 54e1d8c6823..0327602d8ce 100644 --- a/doc/reference/files/dune-project/dialect.rst +++ b/doc/reference/files/dune-project/dialect.rst @@ -1,7 +1,7 @@ dialect ------- -.. dune:stanza:: dialect +.. describe:: (dialect ...) Declare a new :term:`dialect`. diff --git a/doc/reference/files/dune-project/executables_implicit_empty_intf.rst b/doc/reference/files/dune-project/executables_implicit_empty_intf.rst index b16e86bf325..c70e433f04b 100644 --- a/doc/reference/files/dune-project/executables_implicit_empty_intf.rst +++ b/doc/reference/files/dune-project/executables_implicit_empty_intf.rst @@ -1,7 +1,7 @@ executables_implicit_empty_intf ------------------------------- -.. dune:stanza:: executables_implicit_empty_intf +.. describe:: (executables_implicit_empty_intf ...) .. versionadded:: 2.9 diff --git a/doc/reference/files/dune-project/expand_aliases_in_sandbox.rst b/doc/reference/files/dune-project/expand_aliases_in_sandbox.rst index dfdc24fb3dd..3a95222ebf4 100644 --- a/doc/reference/files/dune-project/expand_aliases_in_sandbox.rst +++ b/doc/reference/files/dune-project/expand_aliases_in_sandbox.rst @@ -1,7 +1,7 @@ expand_aliases_in_sandbox ------------------------- -.. dune:stanza:: expand_aliases_in_sandbox +.. describe:: (expand_aliases_in_sandbox ...) When a sandboxed action depends on an alias, copy the expansion of the alias inside the sandbox. For instance, in the following example: diff --git a/doc/reference/files/dune-project/explicit_js_mode.rst b/doc/reference/files/dune-project/explicit_js_mode.rst index 83675e6cb5d..0058313fbbf 100644 --- a/doc/reference/files/dune-project/explicit_js_mode.rst +++ b/doc/reference/files/dune-project/explicit_js_mode.rst @@ -1,7 +1,7 @@ explicit_js_mode ---------------- -.. dune:stanza:: explicit_js_mode +.. describe:: (explicit_js_mode ...) Do not implicitly add ``js`` to the ``(modes ...)`` field of executables. diff --git a/doc/reference/files/dune-project/formatting.rst b/doc/reference/files/dune-project/formatting.rst index 77ea6f12f12..205c817a913 100644 --- a/doc/reference/files/dune-project/formatting.rst +++ b/doc/reference/files/dune-project/formatting.rst @@ -1,7 +1,7 @@ formatting ---------- -.. dune:stanza:: formatting +.. describe:: (formatting ...) .. versionadded:: 2.0 diff --git a/doc/reference/files/dune-project/generate_opam_files.rst b/doc/reference/files/dune-project/generate_opam_files.rst index 70dbbdadb41..cbd40bf151d 100644 --- a/doc/reference/files/dune-project/generate_opam_files.rst +++ b/doc/reference/files/dune-project/generate_opam_files.rst @@ -1,7 +1,7 @@ generate_opam_files ------------------- -.. dune:stanza:: generate_opam_files +.. describe:: (generate_opam_files ...) Use metadata specified in the ``dune-project`` file to generate ``.opam`` files. @@ -18,8 +18,7 @@ generate_opam_files Dune uses the following global fields to set the metadata for all packages defined in the project: -.. dune:stanza:: license - :param: +.. describe:: (license ) Specify the license of the project, ideally as an identifier from the `SPDX License List `__. @@ -32,8 +31,7 @@ defined in the project: Multiple licenses may be specified. -.. dune:stanza:: authors - :param: +.. describe:: (authors ) Specify authors. @@ -45,8 +43,7 @@ defined in the project: "Jane Doe " "John Doe ") -.. dune:stanza:: maintainers - :param: +.. describe:: (maintainers ) Specify maintainers. @@ -58,7 +55,7 @@ defined in the project: "Jane Doe " "John Doe ") -.. dune:stanza:: source +.. describe:: (source ...) Specify where the source for the package can be found. @@ -90,8 +87,7 @@ defined in the project: (source (uri https://dev.example.com/project.git)) -.. dune:stanza:: bug_reports - :param: +.. describe:: (bug_reports ) Where bugs should be reported. @@ -103,8 +99,7 @@ defined in the project: (bug_reports https://dev.example.com/project/issues) -.. dune:stanza:: homepage - :param: +.. describe:: (homepage ) The homepage of the project. @@ -116,8 +111,7 @@ defined in the project: (bug_reports https://example.com/) -.. dune:stanza:: documentation - :param: +.. describe:: (documentation ) Where the documentation is hosted. diff --git a/doc/reference/files/dune-project/implicit_transitive_deps.rst b/doc/reference/files/dune-project/implicit_transitive_deps.rst index e0cdbb6b783..37ab008b2f8 100644 --- a/doc/reference/files/dune-project/implicit_transitive_deps.rst +++ b/doc/reference/files/dune-project/implicit_transitive_deps.rst @@ -1,7 +1,7 @@ implicit_transitive_deps ------------------------ -.. dune:stanza:: implicit_transitive_deps +.. describe:: (implicit_transitive_deps ...) Control whether transitive dependencies are made implicitly visible. diff --git a/doc/reference/files/dune-project/map_workspace_root.rst b/doc/reference/files/dune-project/map_workspace_root.rst index 2d26a37a01e..c52c8bcca11 100644 --- a/doc/reference/files/dune-project/map_workspace_root.rst +++ b/doc/reference/files/dune-project/map_workspace_root.rst @@ -1,8 +1,7 @@ map_workspace_root ------------------- -.. dune:stanza:: map_workspace_root - :param: +.. describe:: (map_workspace_root ) Control references to the file system locations where the project has been built. diff --git a/doc/reference/files/dune-project/name.rst b/doc/reference/files/dune-project/name.rst index 3c2fcd448ef..64748db7369 100644 --- a/doc/reference/files/dune-project/name.rst +++ b/doc/reference/files/dune-project/name.rst @@ -1,8 +1,7 @@ name ---- -.. dune:stanza:: name - :param: +.. describe:: (name ) Set the name of the project. diff --git a/doc/reference/files/dune-project/opam_file_location.rst b/doc/reference/files/dune-project/opam_file_location.rst index be10055ea7d..32ecaf24bc6 100644 --- a/doc/reference/files/dune-project/opam_file_location.rst +++ b/doc/reference/files/dune-project/opam_file_location.rst @@ -1,8 +1,7 @@ opam_file_location ------------------ -.. dune:stanza:: opam_file_location - :param: +.. describe:: (opam_file_location ) .. versionadded:: 3.8 diff --git a/doc/reference/files/dune-project/package.rst b/doc/reference/files/dune-project/package.rst index 4f271978e2b..f90580ff31a 100644 --- a/doc/reference/files/dune-project/package.rst +++ b/doc/reference/files/dune-project/package.rst @@ -1,7 +1,7 @@ package ------- -.. dune:stanza:: package +.. describe:: (package ...) Define package-specific metadata. diff --git a/doc/reference/files/dune-project/subst.rst b/doc/reference/files/dune-project/subst.rst index 82e567566f4..906e460fa2b 100644 --- a/doc/reference/files/dune-project/subst.rst +++ b/doc/reference/files/dune-project/subst.rst @@ -1,8 +1,7 @@ subst ----- -.. dune:stanza:: subst - :param: +.. describe:: (subst ) .. versionadded: 3.0 diff --git a/doc/reference/files/dune-project/use_standard_c_and_cxx_flags.rst b/doc/reference/files/dune-project/use_standard_c_and_cxx_flags.rst index 36147cb02e5..1c83f943f66 100644 --- a/doc/reference/files/dune-project/use_standard_c_and_cxx_flags.rst +++ b/doc/reference/files/dune-project/use_standard_c_and_cxx_flags.rst @@ -1,7 +1,7 @@ use_standard_c_and_cxx_flags ---------------------------- -.. dune:stanza:: use_standard_c_and_cxx_flags +.. describe:: (use_standard_c_and_cxx_flags ...) .. versionadded:: 2.8 diff --git a/doc/reference/files/dune-project/using.rst b/doc/reference/files/dune-project/using.rst index 297490ebf83..a32241f1795 100644 --- a/doc/reference/files/dune-project/using.rst +++ b/doc/reference/files/dune-project/using.rst @@ -1,8 +1,7 @@ using ----- -.. dune:stanza:: using - :param: +.. describe:: (using ) Enable a dune language extension. diff --git a/doc/reference/files/dune-project/version.rst b/doc/reference/files/dune-project/version.rst index 30bf2c511ea..c18b16ebf6e 100644 --- a/doc/reference/files/dune-project/version.rst +++ b/doc/reference/files/dune-project/version.rst @@ -1,8 +1,7 @@ version ------- -.. dune:stanza:: version - :param: +.. describe:: (version ) Set the version of the project. diff --git a/doc/reference/files/dune-project/warnings.rst b/doc/reference/files/dune-project/warnings.rst index c3c7e066f41..13e330e6926 100644 --- a/doc/reference/files/dune-project/warnings.rst +++ b/doc/reference/files/dune-project/warnings.rst @@ -1,7 +1,7 @@ warnings -------- -.. dune:stanza:: warnings +.. describe:: (warnings ...) .. versionadded:: 3.11 diff --git a/doc/reference/files/dune-project/wrapped_executables.rst b/doc/reference/files/dune-project/wrapped_executables.rst index 2cd6f162422..a498fdb31a0 100644 --- a/doc/reference/files/dune-project/wrapped_executables.rst +++ b/doc/reference/files/dune-project/wrapped_executables.rst @@ -1,8 +1,7 @@ wrapped_executables ------------------- -.. dune:stanza:: wrapped_executables - :param: +.. describe:: (wrapped_executables ) .. versionadded:: 1.11 diff --git a/doc/reference/files/dune/cram.rst b/doc/reference/files/dune/cram.rst index 0e497c1514d..517ce3446fe 100644 --- a/doc/reference/files/dune/cram.rst +++ b/doc/reference/files/dune/cram.rst @@ -1,7 +1,7 @@ Cram ---- -.. dune:stanza:: cram +.. describe:: (cram ...) Configure Cram tests in the current directory (and subdirectories).