Inline code

Sphinx supports different ways to mark up inline code.

On this page

To mark up code in inline text, you can:

  • Surround the code with two backtick characters.

  • Use the code interpreted text role.

Syntax highlighting in inline code

By default, Sphinx doesn’t highlight inline code. With the following extra steps, you can enable it.

  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:

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

    This makes docutils use short class names for syntax highlighting, the same setting as Sphinx uses to highlight code blocks.

    Note

    This is necessary so that you can re-use the 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, to highlight inline Python code, add the following code to the beginning of the reStructuredText file, in which you want to use the highlighting:

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

    This renders a code element with a class of highlight, which uses the highlighting styles from Pygments—the same as for code blocks.

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

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

    This renders print("Hello World").

Interpreted text roles for code-like elements

Docutils and Sphinx come with many interpreted text roles to mark up specific elements. While this can be useful to convey semantic intentions in the reStructuredText source files, it’s a good idea to use only a few different roles:

  • The difference between the many roles are lost in the rendered output. Most of these roles are rendered in code font, and most users don’t read the reStructuredText sources.

  • Using too many directives puts a burden on documentation writers, who may be more familiar with the Markdown format. They have to agree and remember when to use which role.

The awesome theme only provides styles for the following interpreted text roles.

Files and directories

You can designate files with the file role.

rst
:file:`Some file name`

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

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

This renders as /home/USERNAME/. If you want to distinguish directories from file names, 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:

rst
:samp:`Replace {PLACEHOLDER}`

This renders as Replace PLACEHOLDER.

Keyboard input

You can highlight keyboard combinations using the kbd interpreted text role:

rst
:kbd:`Ctrl+F`

This renders as Ctrl+F.

Interpreted text roles for graphical user interface documentation

Graphical user interface elements are often rendered in a bold font, in contrast to the monospace font for code elements.

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

rst
:guilabel:`Help`

This renders as Help.

Use the menuselection role to document items in menus.

rst
:menuselection:`Start --> Program`

This renders as Start ‣ Program.