Docstring Table Rendering Issues in VS Code

Improving code documentation using Markdown tables. Comparing reStructuredText and Markdown tables in Visual Studio Code.

This article compares reStructuredText (reST) and Markdown tables in VS code and investigates docstring table rendering issues with reST.

Photo by Clément Hélardot on Unsplash.

reStructuredText Tables

reST is the default markup language for Sphinx, a tool for generating Python documentation. While reStructuredText is a common choice for writing docstrings, it has trouble rendering in VS Code:

Table Comparison — Screenshots by Author.

Markdown Tables

To avoid rendering issues in VS code, we can use Markdown tables instead. Markdown is simple and readable. And VS Code supports it. When you write a table in Markdown and hover over the function, the table renders correctly:

Screenshot by Oliver Lövström.

Markdown Table Syntax

To use Markdown for your tables:

• Pipes | create columns
• Dashes - under the header row, separating it from the content rows

See the example below:

|   A   |   B   | A and B |
| :---  | :---  | :-----: |
| False | False |  False  |
| True  | False |  False  |
| False | True  |  False  |
| True  | True  |  True   |

def markdown_table() -> None:
    """Markdown table.

    |   A   |   B   | A and B |
    | :---  | :---  | :-----: |
    | False | False |  False  |
    | True  | False |  False  |
    | False | True  |  False  |
    | True  | True  |  True   |
    """

    return None

Markdown and Sphinx

Sphinx now supports Markdown through the MyST-Parser extension. This tool allows Sphinx documentation, including tables, to be written in Markdown.

Further Reading

If you want to learn more about programming and, specifically, Python and Java, see the following Coursera course:

Introduction to Programming with Python and Java

Note: If you use my links to order, I’ll get a small kickback.