feature: code-block directive rendering

[nbanyan]

Requested Feature

Rendering of Sphinx code block directives code, sourcecode, and code-block.

.. code-block:: bash

    custom_command arg1 ['option1', 'option2'] ['option3']

Currently, directives are processed directly as markdown, which can cause cross-reference error messages for docstrings like this.

Proposed Solution

Detect code directives and convert them to Markdown fenced code blocks when rendering for MkDocs.

The above example would become:

``` bash
custom_command arg1 ['option1', 'option2'] ['option3']

### Alternatives

Manually converting the code-block comments when I catch them being added...

### Additional Queries

Are directives already handled in the Insider's version?

[pawamoy]

Hi @nbanyan, thanks for the request. If I understand correctly, you're using Griffe through MkDocs and mkdocstrings-python. MkDocs expects Markdown, so we won't add any kind of support for reStructuredText markup. I recommend you convert your docstrings to Markdown, or write a Python-Markdown extension that converts rST to Markdown on the fly 🙂