Repository: twisted/pydoctor

Issue:
Colorize code inside ``..code ::`` directives
The code currently only displayed as a literal block, but no syntax highlight is applied. 
I think we could re-use the doctest syntaxt highlight and apply it to the ``..code ::`` directive, too.

Comments:

Patch:
diff --git a/docs/source/docformat/list-restructuredtext-support.rst b/docs/source/docformat/list-restructuredtext-support.rst
index 1aea3679..c4d184d6 100644
--- a/docs/source/docformat/list-restructuredtext-support.rst
+++ b/docs/source/docformat/list-restructuredtext-support.rst
@@ -60,7 +60,7 @@ List of ReST directives
 
    * - ``.. code::``
      - `docutils <https://docutils.sourceforge.io/docs/ref/rst/directives.html#code>`__
-     - Yes
+     - Yes (No options supported)
 
    * - ``.. python::``
      - pydoctor
@@ -144,7 +144,7 @@ List of ReST directives
 
    * - ``.. code-block::``
      - `Sphinx <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`__
-     - No
+     - Yes (No options supported)
 
    * - ``.. literalinclude::``
      - `Sphinx <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude>`__
diff --git a/docs/source/docformat/restructuredtext.rst b/docs/source/docformat/restructuredtext.rst
index ee5fb63f..7baf4d9f 100644
--- a/docs/source/docformat/restructuredtext.rst
+++ b/docs/source/docformat/restructuredtext.rst
@@ -88,10 +88,10 @@ Here is a list of the supported ReST directives by package of origin:
 
 - `docutils`: ``.. include::``, ``.. contents::``, ``.. image::``,
   ``.. figure::``, ``.. unicode::``, ``.. raw::``, ``.. math::``,
-  ``.. role::``, ``.. table::``, ``.. warning::``, ``.. note::``
+  ``.. role::``, ``.. table::``, ``.. code::``, ``.. warning::``, ``.. note::``
   and other admonitions, and a few others.
-- `epydoc`: None
-- `Sphinx`: ``.. deprecated::``, ``.. versionchanged::``, ``.. versionadded::``
+- `epydoc`: None yet.
+- `Sphinx`: ``.. deprecated::``, ``.. versionchanged::``, ``.. versionadded::``, ``.. code-block::``
 - `pydoctor`: ``.. python::``
 
 `Full list of supported and unsupported directives <list-restructuredtext-support.html>`_
@@ -102,8 +102,12 @@ Colorized snippets directive
 Using reStructuredText markup it is possible to specify Python snippets in a
 `doctest block <https://docutils.sourceforge.io/docs/user/rst/quickref.html#doctest-blocks>`_.
 
+
 If the Python prompt gets in your way when you try to copy and paste and you are not interested
-in self-testing docstrings, the python directive will let you obtain a simple block of colorized text::
+in self-testing docstrings, the python directive will let you obtain a simple block of colorized text. 
+Directives ``.. code::`` and ``.. code-block::`` acts exactly the same.
+
+::
 
     .. python::
 
diff --git a/pydoctor/epydoc/markup/restructuredtext.py b/pydoctor/epydoc/markup/restructuredtext.py
index edb640fa..a189bec4 100644
--- a/pydoctor/epydoc/markup/restructuredtext.py
+++ b/pydoctor/epydoc/markup/restructuredtext.py
@@ -482,13 +482,35 @@ class PythonCodeDirective(Directive):
     """
 
     has_content = True
-
+    
     def run(self) -> List[nodes.Node]:
         text = '\n'.join(self.content)
         node = nodes.doctest_block(text, text, codeblock=True)
         return [ node ]
 
+class DocutilsAndSphinxCodeBlockAdapter(PythonCodeDirective):
+    # Docutils and Sphinx code blocks have both one optional argument, 
+    # so we accept it here as well but do nothing with it.
+    required_arguments = 0
+    optional_arguments = 1
+
+    # Listing all options that docutils.parsers.rst.directives.body.CodeBlock provides
+    # And also sphinx.directives.code.CodeBlock. We don't care about their values, 
+    # we just don't want to see them in self.content.
+    option_spec = {'class': directives.class_option,
+                'name': directives.unchanged,
+                'number-lines': directives.unchanged, # integer or None
+                'force': directives.flag,
+                'linenos': directives.flag,
+                'dedent': directives.unchanged, # integer or None
+                'lineno-start': int,
+                'emphasize-lines': directives.unchanged_required,
+                'caption': directives.unchanged_required,
+    }
+
 directives.register_directive('python', PythonCodeDirective)
+directives.register_directive('code', DocutilsAndSphinxCodeBlockAdapter)
+directives.register_directive('code-block', DocutilsAndSphinxCodeBlockAdapter)
 directives.register_directive('versionadded', VersionChange)
 directives.register_directive('versionchanged', VersionChange)
 directives.register_directive('deprecated', VersionChange)


Test patch:
diff --git a/pydoctor/test/epydoc/restructuredtext.doctest b/pydoctor/test/epydoc/restructuredtext.doctest
index 9438f8c7..a9aee4e3 100644
--- a/pydoctor/test/epydoc/restructuredtext.doctest
+++ b/pydoctor/test/epydoc/restructuredtext.doctest
@@ -104,3 +104,30 @@ as colorized Python code.
 <span class="py-keyword">class</span> <span class="py-defname">Foo</span>:
     <span class="py-keyword">def</span> <span class="py-defname">__init__</span>(self):
         <span class="py-keyword">pass</span></pre>
+>>> p = restructuredtext.parse_docstring(
+... """The directives options are ignored and do not show up in the HTML.
+... 
+... .. code:: python
+...     :number-lines:
+...     :linenos:
+...
+...     # This is some Python code
+...     def foo():
+...         pass
+...
+...     class Foo:
+...         def __init__(self):
+...             pass
+... """, err)
+>>> err
+[]
+>>> print(flatten(p.to_stan(None)))
+<p>The directives options are ignored and do not show up in the HTML.</p>
+<pre class="py-doctest">
+<span class="py-comment"># This is some Python code</span>
+<span class="py-keyword">def</span> <span class="py-defname">foo</span>():
+    <span class="py-keyword">pass</span>
+<BLANKLINE>
+<span class="py-keyword">class</span> <span class="py-defname">Foo</span>:
+    <span class="py-keyword">def</span> <span class="py-defname">__init__</span>(self):
+        <span class="py-keyword">pass</span></pre>
\ No newline at end of file