Sphinx - Use ellipses (…) in code-block snippets

Question

Consider you document a long code snippet and you want to represent repetitive values and lines in it with ellipses … (…) and vertical ellipses &vellip; (&vellip;).

Here's an example record in JSON. There are 26 kids and you don't want to show all of them.

.. code-block:: json

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

Human readers can still see this as a JSON snippet/code, generalize and guess the pattern between "Becky" and "Zoe" represented by the ellipsis (...).

But Sphinx returns the error because this snippet has an invalid syntax.

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

Can I use ellipses in code-block (with syntax highlighting)? Please note the example doesn't have to be in JSON. You will see this issue in other languages such as Python too.

Try the `:force:` option (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive:option-code-block-force). — mzjn, Dec 21 '19 at 08:24
If `:foce:` does not work, there are less appealing options. Unfortunately, JSON does not support comments. For languages that do support comments but treat ellipses as a syntax error, I comment out the ellipses. If you don't mind dirtying up your JSON data, you could insert a data element `{"MOAR_KIDS": 999},` and surround it with a lot of whitespace. — Steve Piercy, Dec 22 '19 at 04:24

score 3 · Accepted Answer · answered Dec 22 '19 at 23:39

3

Add the option :force: and add custom CSS to disable the error highlighting:

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

answered Dec 22 '19 at 23:39

Culip

559
8
24

Dedication: This answer is based on mzjn and Steve Piercy. – Culip Dec 22 '19 at 23:40

Sphinx - Use ellipses (…) in code-block snippets

1 Answers1