sphinx / doc / markup / inline.rst

Inline markup

Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as :rolename:`content`.


The default role (`content`) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the :confval:`default_role` config value to set it to a known role.

See :ref:`domains` for roles added by domains.

Cross-referencing syntax

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write :role:`target`, and a link will be created to the item named target of the type indicated by role. The links's text will be the same as target.

There are some additional facilities, however, that make cross-referencing roles more versatile:

  • You may supply an explicit title and reference target, like in reST direct hyperlinks: :role:`title <target>` will refer to target, but the link text will be title.

  • If you prefix the content with !, no reference/hyperlink will be created.

  • If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.

    In HTML output, the link's title attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name.

Cross-referencing arbitrary locations

Cross-referencing documents

There is also a way to directly link to documents:

Referencing downloadable files

Other semantic markup

The following roles don't do anything special except formatting the text in a different style:

The following roles generate external links:

Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose.

Cross-referencing other items of interest

The following roles do possibly create a cross-reference, but do not refer to objects:

The following role creates a cross-reference to the term in the glossary:


The documentation system provides three substitutions that are defined by default. They are set in the build configuration file.