2

I'm using Read the Docs for the first time. I'm writing docs for a command line system, and my "code samples" include a log of shell output. The shell output ends up looking like this

image of shell output that read the docs has attempted to format as though it was source code resulting in some weird choices

That is -- the service (or my use of it?) is trying to format this example of running a shell command as though it was source code, and is treating the magento2:generate as though it was a class constant.

Can I control which code blocks get source code formatting in read the docs? I've tried setting no base language in the admin, but it doesn't seem to have an effect. Or is this something I need to control at the mkdocs of sphinx level? (read the docs works by turning your markdown or sphinx files into nice HTML files) Or something else? Or am I out of luck?

barryhunter
  • 20,886
  • 3
  • 30
  • 43
Alana Storm
  • 164,128
  • 91
  • 395
  • 599
  • 1
    With Sphinx and reStructuredText, you can use the `code-block` directive with `sh` (or perhaps `console`) as the language. http://www.sphinx-doc.org/en/stable/usage/restructuredtext/directives.html#directive-code-block – mzjn Jul 03 '19 at 16:22
  • 1
    To add to @mzjn, syntax highlighting in Sphinx (which is used by RTD) is provided through Pygments with thingies called "lexers". See the [complete list of lexers](http://pygments.org/docs/lexers/). Note that most, but not all, are supported. Specifically see the [shell lexers](http://pygments.org/docs/lexers/#lexers-for-various-shells). – Steve Piercy Jul 03 '19 at 23:13

1 Answers1

5

You need to define the "language" of the code block in your source document. Both Sphinx and MkDocs will attempt to guess the language, which often is good enough. However, on occasion, it will guess incorrectly and result in weird highlighting. To avoid that, both implementations provide a mechanism to manually define the language of each code block.

Sphinx

For Sphinx, you can use the code-block directive and include the "language" of the block:

.. code-block:: console

    You shell commands go here

In the above example, I used console for the a shell session. The alias shell-session would work as well. Note that the alternative lexer bash (and its aliases: sh, ksh, zsh, and shell) woudl not strictly be appropriate as they are for a shell script, whereas you are displaying both the command and theoutput in a shell session.

A complete list of supported language codes can be found in the Pygments documentation.

MkDocs

MkDocs makes use of the Fenced Code Block Markdown extension to define the "language" of a code block:

``` shell
Your shell commands go here
```

As MkDocs uses highlight.js rather than Pygments, the list of supported languages is different. Therefore, I used shell (for a shell-session) in the above example.

Waylan
  • 37,164
  • 12
  • 83
  • 109