Sphinx - 在代码块片段中使用省略号 (...)答案

【问题标题】：Sphinx - Use ellipses (…) in code-block snippetsSphinx - 在代码块片段中使用省略号 (...)
【发布时间】：2019-12-20 21:00:51
【问题描述】：

假设您记录了一个长代码 sn-p，并且您想用省略号 ... (&hellip;) 和垂直省略号 &vellip; 来表示其中的重复值和行。 (&vellip;)。

这是 JSON 格式的示例记录。有 26 个孩子，您不想全部展示。

.. code-block:: json

   {
       "total": 26,
       "kids" [
           {
               "_id":  1,
               "name": "Alice",
               "age":  3
           },
           {
               "_id":  2,
               "name": "Becky",
               "age":  3
           },
           ...,
           {
               "_id":  26,
               "name": "Zoe",
               "age":  4
           }
       ]
   }

人类读者仍然可以将其视为 JSON sn-p/code，概括并猜测省略号 ( ...)。

但是 Sphinx 会返回错误，因为这个 sn-p 的语法无效。

$ make html
...
/.../docs/source/sample.rst:3: WARNING: Could not lex literal_block as "json". Highlighting skipped.

我可以在代码块中使用省略号（带有语法高亮）吗？请注意，示例不一定是 JSON。您也会在其他语言（例如 Python）中看到此问题。

【问题讨论】：

试试:force:选项（sphinx-doc.org/en/master/usage/restructuredtext/…）。
如果:foce: 不起作用，那么吸引人的选项就更少了。不幸的是，JSON 不支持 cmets。对于支持 cmets 但将省略号视为语法错误的语言，我将省略号注释掉。如果您不介意弄脏您的 JSON 数据，您可以插入一个数据元素 {"MOAR_KIDS": 999}, 并用大量空格包围它。

标签： python-sphinx

【解决方案1】：

添加选项 :force: 并添加自定义 CSS 以禁用错误突出显示：

.highlight .err {
    border: inherit;
    box-sizing: inherit;
}

【讨论】：

奉献：此答案基于 mzjn 和 Steve Piercy。