0

I've followed along the answers presented here as to achieving colored text in .rst - documents (i.e. the HTML-preview associated with them).

Yet, inside a code-environment, it does not work: vs-code-rst-colored-text

How can I make colored text work inside the code-environment?

The code of my entire .rst - file is:

.. raw:: html

    <style> .red {color:red} </style>

.. role:: red



Amazon States Language
======================

Source: https://states-language.net/spec.html


Key-facts
----------

1) JSON-based language used to describe state machines declaratively
2) State Machine are represented by a JSON Object(s) == "states"
3) State machines thus defined may be executed by software ("the interpreter")


Hello-World
---------------------

An example of using :red:`interpreted text`

.. code:: JSON

    {
        "Comment": "A simple minimal example of the States language",  //:red:`optional`
        "Version": "1.0",  //:red:`optional`
        "TimeoutSeconds": 10,  //:red:`optional`
        "StartAt": "Hello World",  //required
        "States": {  //required
            "Hello World": {
                "Type": "Task",
                "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
                "End": true
            }
        }
    }

PS on trying out workarounds (which failed):

1. Space character in front:
Putting a space character between the // and e.g. :red:'optional' did not resolve the problem. I realized later that inserting a space character in front of the colored text piece makes things work, but what if you do not want a space in front?

2. CSS-inline with !important:
It did not lead to any difference in the output HTML.

.. raw:: html

    <style> .red {color: red !important} </style>
    <style> .green {color: green !important} </style>

.. role:: red
.. role:: green

3. Change to programming language which supports comments (Python):
It also does not work, no colors are displayed either. The code is the following:

.. code:: python

    {
        "Comment":
        "A simple minimal example of the States language",  # :green:`optional`
        "Version": "1.0",  # :green:`optional`
        "TimeoutSeconds": 10,  # :green:`optional`
        "StartAt": "Hello World",  # :red:`required`
        "States": {  # :red:`required`
            "Hello World": {  # :red:`must be unique within state machine`
                "Type": "Task",  # :red:`required`
                "Resource":
                "arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
                "End": true,  # terminal state
                "Comment":
                "Executes the HelloWorld Lambda function"  # :green:`optional`
            }
        }
    }
Andreas L.
  • 3,239
  • 5
  • 26
  • 65
  • code-block supports only the syntax highlighting of the language. JSON does not support comments. For languages that support comments, you could override the applied style. – Steve Piercy Jun 11 '21 at 05:18
  • So one solution would be changing `.. code:: JSON` to `.. code:: python` and replace all the `//` with `#`? Apart from that, I tried out HJSON which supports comments (https://hjson.github.io/ ), but unfortunately the HTML-interpreter of the .rst-file throws the following error: `Cannot analyze code. No Pygments lexer found for "HJSON"`. – Andreas L. Jun 11 '21 at 09:00
  • I've just tried with `Python`, it did not work either even though it supports commands via `#` (see 3rd edit in my OP). – Andreas L. Jun 11 '21 at 09:08
  • Concerning the `config.json` - file, which is mentioned in the context of `sphinx` in an ubiquitous manner, do I have to create such a file every time I save an `.rst`-file somewhere on my system? I actually hoped I could just use some `VS-Code` extensions in a way that everything is recognized automatically correctly, or simply add something into the `settings.json` of `VS-Code` , such as e.g. `"restructuredtext.updateOnTextChanged" : "true"` etc. – Andreas L. Jun 11 '21 at 09:39
  • What `config.json` file are you talking about? Sphinx has a `conf.py` file, and no `config.json` file. – Steve Piercy Jun 12 '21 at 07:37
  • I said "supports *comments*" not *commands*. Sphinx will use Pygments to provide syntax highlighting of code. That code cannot be interpreted as reStructuredText. A comment would be rendered as a comment with a single "comment-ish" style. You could use raw HTML and custom CSS. – Steve Piercy Jun 12 '21 at 07:54
  • Oh yes, I actually meant "comments" and `conf.py`, those were just typos. – Andreas L. Jun 14 '21 at 07:28
  • So, in order to solve the problem, I would have to write somewhere raw `HTML` or `CSS` specifications in the beginning of my `.rst`? I'd be delighted if you could provide me a working example, as I don't have the expertise to do it. – Andreas L. Jun 14 '21 at 09:24
  • Honestly, I would not use color-coding at all. It's not good for accessibility. It is better to provide a separate table that has each of the JSON keys and values with its attributes (type, required/optional, length, range, etc.). If it is an API, then have a look at https://petstore.swagger.io/ There are lots of options that can make documentation clear to the reader. – Steve Piercy Jun 14 '21 at 11:35
  • Alright, thanks for your opinion and tips. – Andreas L. Jun 14 '21 at 12:42

0 Answers0