cmdref: codeblock language now works

Add `options` map for setting `ContentListing` options with key:val pairs; currently only used with `ContentListing::codeblock()` language arg.
Fix generated codeblock rst to print each line of code with indentation, and change it to use explicit an `code-block` so we can set a language on it.

docs/source/cmd/index_internal.rst

@@ -47,7 +47,8 @@ The ``formatted_help()`` method
       added automatically
     * ``codeblock`` content is displayed verbatim, use line breaks as desired;
       takes an optional ``language`` argument for assigning the language in RST
-      output for code syntax highlighting (currently not implemented)
+      output for code syntax highlighting (use ``yoscrypt`` for yosys script
+      syntax highlighting)
     * ``option`` lists a single option for the command, usually starting with a
       dash (``-``); takes an optional second argument which adds a paragraph
       node as a means of description
@@ -62,8 +63,6 @@ The ``formatted_help()`` method
   + paragraphs are treated as raw RST, allowing for inline formatting and
     references as if it were written in the RST file itself
 
-.. todo:: Support ``ContentListing::codeblock`` language argument
-
 .. todo:: Support anonymous optiongroup
 
    If an option is added to the root node it should add the option to the last

docs/util/cmd_documenter.py

@@ -28,6 +28,7 @@ class YosysCmdContentListing:
     body: str
     source_file: str
     source_line: int
+    options: dict[str, str]
     content: list[YosysCmdContentListing]
 
     def __init__(
@@ -36,12 +37,14 @@ class YosysCmdContentListing:
             body: str = "",
             source_file: str = "unknown",
             source_line: int = 0,
+            options: dict[str, str] = {},
             content: list[dict[str]] = [],
     ):
         self.type = type
         self.body = body
         self.source_file = source_file
         self.source_line = source_line
+        self.options = options
         self.content = [YosysCmdContentListing(**c) for c in content]
 
 class YosysCmd:
@@ -375,9 +378,11 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
                 self.add_line(f'{indent_str}{content_list.body}', content_source)
                 self.add_line('', source_name)
             elif content_list.type == 'code':
-                self.add_line(f'{indent_str}::', source_name)
+                language_str = content_list.options.get('language', '')
+                self.add_line(f'{indent_str}.. code-block:: {language_str}', source_name)
                 self.add_line('', source_name)
-                self.add_line(f'{indent_str}   {content_list.body}', content_source)
+                for body_line in content_list.body.splitlines():
+                    self.add_line(f'{indent_str}   {body_line}', content_source)
                 self.add_line('', source_name)
             else:
                 logger.warning(f"unknown content type '{content_list.type}'")

kernel/log_help.cc

@@ -27,6 +27,7 @@ Json ContentListing::to_json() {
 	if (body.length()) object["body"] = body;
 	if (strcmp(source_file, "unknown") != 0) object["source_file"] = source_file;
 	if (source_line != 0) object["source_line"] = source_line;
+	object["options"] = Json(options);
 	Json::array content_array;
 	for (auto child : _content) content_array.push_back(child->to_json());
 	object["content"] = content_array;
@@ -52,6 +53,7 @@ void ContentListing::codeblock(const string &code, const string &language,
 	const source_location location)
 {
 	add_content("code", code, location);
+	back()->set_option("language", language);
 }
 
 void ContentListing::paragraph(const string &text,

kernel/log_help.h

@@ -32,12 +32,14 @@ public:
 	string body;
 	const char* source_file;
 	int source_line;
+	std::map<string, string> options;
 
 	ContentListing(
 		string type = "root", string body = "",
 		const char* source_file = "unknown", int source_line = 0
 	) : type(type), body(body), source_file(source_file), source_line(source_line) {
 		_content = {};
+		options = {};
 	}
 
 	ContentListing(string type, string body, source_location location) :
@@ -61,6 +63,10 @@ public:
 		return _content.back();
 	}
 
+	void set_option(string key, string val = "") {
+		options[key] = val;
+	}
+
 	void usage(
 		const string &usage,
 		const source_location location = source_location::current()