api/apidoc: Add support for code-block directive

swh/web/api/apidoc.py

@@ -190,9 +190,18 @@ class _HTTPDomainDocVisitor(docutils.nodes.NodeVisitor):
         """
         Visit literal blocks
         """
-        text = node.astext()
 
-        return f"\n\n::\n\n{textwrap.indent(text, '   ')}\n"
+        text = node.astext()
+        node_classes = node["classes"]
+        if node_classes and node_classes[0] == "code":
+            language = node_classes[1] if len(node_classes) > 1 else ""
+            # code block will be rendered by highlightjs
+            return (
+                f'\n\n.. raw:: html\n\n    <pre><code class="{language}">'
+                f'{textwrap.indent(text, " "*4)[4:]}</code></pre>'
+            )
+        else:
+            return f"\n\n::\n\n{textwrap.indent(text, '   ')}\n"
 
     def visit_bullet_list(self, node: docutils.nodes.bullet_list) -> str:
         parts = ["\n\n"]
@@ -241,10 +250,12 @@ class _HTTPDomainDocVisitor(docutils.nodes.NodeVisitor):
 
     def visit_block_quote(self, node: docutils.nodes.block_quote) -> str:
         return self._default_visit(node)
-        return (
-            f".. code-block::\n"
-            f"{textwrap.indent(self._default_visit(node), '   ')}\n"
-        )
+
+    def visit_inline(self, node):
+        return self._default_visit(node)
+
+    def visit_code_block(self, node) -> str:
+        return self._default_visit(node)
 
     def visit_title_reference(self, node: docutils.nodes.title_reference) -> str:
         text = self._default_visit(node)

swh/web/api/tests/test_apidoc.py

@@ -597,3 +597,32 @@ def test_apidoc_with_links_in_text(client):
         )
         in html
     )
+
+
+@api_route(r"/endpoint/codeblock-in-doc/", "api-1-endpoint-codeblock-in-doc")
+@api_doc("/endpoint/links/in/doc/", category="test")
+def apidoc_test_endpoint_with_codeblock_in_doc(request):
+    """
+    .. http:get:: /api/1/codeblock-in-doc/endpoint/
+
+        .. code-block:: python
+
+            def add(a, b):
+                return a + B
+
+    """
+    pass
+
+
+def test_apidoc_with_codeblock(client):
+    url = reverse("api-1-endpoint-codeblock-in-doc")
+    rv = check_html_get_response(
+        client, url, status_code=200, template_used="apidoc.html"
+    )
+
+    html = prettify_html(rv.content)
+
+    assert (
+        '         <pre><code class="python">def add(a, b):\n'
+        "    return a + B</code></pre>"
+    ) in html

swh/web/utils/__init__.py

@@ -394,7 +394,7 @@ _HTML_WRITER = Writer()
 _HTML_WRITER.translator_class = _NoHeaderHTMLTranslator
 
 
-def rst_to_html(rst: str) -> str:
+def rst_to_html(rst: str, raw_enabled: bool = False) -> str:
     """
     Convert reStructuredText document into HTML.
 
@@ -410,7 +410,7 @@ def rst_to_html(rst: str) -> str:
         "halt_level": 4,
         "traceback": True,
         "file_insertion_enabled": False,
-        "raw_enabled": False,
+        "raw_enabled": raw_enabled,
     }
     try:
         pp = publish_parts(rst, writer=_HTML_WRITER, settings_overrides=settings)

swh/web/utils/swh_templatetags.py

@@ -23,7 +23,7 @@ def docstring_display(docstring):
     Utility function to htmlize reST-formatted documentation in browsable
     api.
     """
-    return rst_to_html(docstring)
+    return rst_to_html(docstring, raw_enabled=True)
 
 
 @register.filter