如何将高亮或代码块插入 Sphinx 样式的文档字符串？答案

【问题标题】：How do I insert highlight or code-block into Sphinx-style docstrings?如何将高亮或代码块插入 Sphinx 样式的文档字符串？
【发布时间】：2017-10-23 14:46:01
【问题描述】：

例如：

def foo():
    '''
    .. highlight:: python
    import sys
    '''

不产生所需的输出（它逐字打印单词“highlight”并且不以任何特殊方式格式化以下代码）。 code-block 也是如此。

我尝试了不同的缩进等。无论如何，生成器都会以大致相同的方式成功，但不是所需的输出。

【问题讨论】：

你缺少缩进；尝试在导入行前添加 4 个空格
@Vinny 显然，我还需要两者之间的空行！

标签： python python-sphinx docstring

【解决方案1】：

将您的代码与docs 进行比较，您在突出显示和实际代码之间缺少缩进和空行。应该是这样的：

def foo():
    '''
    .. highlight:: python
    .. code-block:: python

        import sys
        ...
    '''

【讨论】：

这还不够。代码必须在文字块中（前一段以::结尾的块）。
编辑后的内容确实有效但多余。 .. highlight:: python 可以删除。
请参阅stackoverflow.com/a/50956831/1497139 以获得更好的解释