Search code examples
magentopython-sphinxread-the-docsmkdocs

Code Formatting for the ReadTheDocs System

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?

Solution

  • 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.