Inline code

See how inline markup looks like in the Awesome Theme.

To mark up code in inline text, you can:

  • Surround the code with two backtick characters.

  • Use the code interpreted text role.

If you want to see the styles for code blocks, see Code blocks.

Syntax highlighting in inline code

By default, Sphinx doesn’t highlight inline code. To highlight inline code with Sphinx, follow these steps:

  1. Create a docutils configuration file docutils.conf in the same directory as the Sphinx configuration file conf.py.

  2. Add to the docutils configuration file docutils.conf:

    File: docutils.conf
    [restructuredtext parser]
syntax_highlight = short

    Note

    This option makes Pygments use short class names for the highlighted code. This lets you re-use the same Pygments style sheet pygments.css that Sphinx already uses for code blocks.

  3. For each language you want to highlight, create a custom interpreted text role using docutils’ role directive.

    For example, add this code to the beginning of an reStructuredText file:

    .. role:: python(code)
  :language: python
  :class: highlight

    This lets you highlight inline Python code. Adding the highlight class lets you re-use the Pygments CSS styles that Sphinx already uses for code blocks.

  4. Use the new role to highlight inline code. For example:

    :python:`print("Hello World")`

    This renders print("Hello World").

More interpreted text roles

Docutils and Sphinx have many interpreted text roles. They can be useful to convey precise semantic intentions in the reStructuredText source files. On the other hand, it might be better to only use a few different roles:

  • The difference between the many roles are lost in the rendered output. Most of these roles are rendered like code (or bold).

  • Using too many directives puts a burden on documentation writers, who have to agree and remember when to use which role.

The Awesome Theme provides styles for the following interpreted text roles.

Files and directories

You can designate files with the file role.

:file:`Some file name`

This renders as Some filename. You can highlight placeholder text in file and directory names using the following syntax:

:file:`/home/{USERNAME}/`

This renders as /home/USERNAME/.

Tip

To distinguish directories from files, you can append a Slash (/) character to directory names.

Inline code with placeholder text

To highlight inline code with placeholder text, use the samp interpreted text role:

:samp:`Replace {PLACEHOLDER}`

This renders as Replace PLACEHOLDER.

Keyboard input

Highlight keyboard shortcuts with the kbd interpreted text role:

:kbd:`Ctrl+F`

This renders as Ctrl+F.

User interface elements

Use the guilabel role to highlight user interface elements, such as buttons:

:guilabel:`Help`

This renders as Help.

Use the menuselection role to document items in menus.

:menuselection:`Start --> Program`

This renders as Start ‣ Program.