From b4ccaf8c089692dc009f3fbe10fe82031718d6b0 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 21 Mar 2025 10:26:13 +1300
Subject: [PATCH] autocmd_rst: autodoc for generated RST

Adds `autocmd_rst` directive, which effectively calls `autocmd` for the same command, but wraps it in a code-block in order to render the raw RST generated.
---
 docs/util/cmd_documenter.py | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/util/cmd_documenter.py b/docs/util/cmd_documenter.py
index 2b93772e8..bf71a00ac 100644
--- a/docs/util/cmd_documenter.py
+++ b/docs/util/cmd_documenter.py
@@ -403,11 +403,35 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
 
         return False, []
 
+class YosysCmdRstDocumenter(YosysCmdDocumenter):
+    objtype = 'cmd_rst'
+    priority = 0
+
+    @classmethod
+    def can_document_member(cls, *args) -> bool:
+        return False
+
+    def add_directive_header(self, sig):
+        source_name = self.object.source_file
+        cmd = self.object.name
+        self.add_line(f'.. code-block:: rst', source_name)
+        self.add_line(f'   :caption: Generated rst for ``.. autocmd:: {cmd}``', source_name)
+
+    def add_content(self, more_content):
+        source_name = self.object.source_file
+        cmd = self.object.name
+        self.domain = 'cmd'
+        super().add_directive_header(cmd)
+        self.add_line('', source_name)
+        self.indent += self.content_indent
+        super().add_content(more_content)
+
 def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('cmds_json', False, 'html', [Path, PosixPath, WindowsPath])
     app.setup_extension('sphinx.ext.autodoc')
     app.add_autodocumenter(YosysCmdGroupDocumenter)
     app.add_autodocumenter(YosysCmdDocumenter)
+    app.add_autodocumenter(YosysCmdRstDocumenter)
     return {
         'version': '2',
         'parallel_read_safe': True,