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

Posted 2023-03-30

【中文标题】Sphinx - 在代码块片段中使用省略号 (...)

【英文标题】：Sphinx - Use ellipses (…) in code-block snippets

【发布时间】：2019-12-20 21:00:51

【问题描述】：

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

这是 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, 并用大量空格包围它。

【参考方案1】：

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

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

【讨论】：

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