Inline code and text roles 

This page

How to markup specific text semantically 

There are several ways to semantically mark specific parts of the text. The main goal is to be able to use a consistent style for specific parts of the text, for example code fragments, file names and GUI elements.

Preferred: Use Sphinx interpreted text roles to explicitly specify what kind of text / code (= textrole) it is. This shows the semantics and in the output there may be a a special coloring or highlighting:

Using text roles 

Self defined interpreted text roles 

See also file /Includes.rst.txt, if present in a project.

Role Source Output Note
(default) `result = (1 + x) * 32` result = (1 + x) * 32 This works because in /Includes.rst.txt we set the default role to :code:`...`
aspect :aspect:`Description:` Description: For better optics
html :html:`<a href="#">` <a href="#">  
issue :issue:`12345` forge#12345 To link to a TYPO3 issue.
js :js:`var f = function () {return 1;}` var f = function () {return 1;}  
php :php:`$result = $a + 23;` $result = $a + 23;  
sep :sep:`|` | To give the separator '|' a special style in some contexts like :ref:`Styled-Definition-Lists`
ts :ts:`lib.hello.value = Hello World!` lib.hello.value = Hello World!  
typoscript :typoscript:`lib.hello.value = Hello World!` lib.hello.value = Hello World!  
yaml :yaml:`- {name: John Smith, age: 33}` - {name: John Smith, age: 33}  

Examples for direct use 

  • code
  • samp
  • fluid
  • css
  • scss
  • html
  • input
  • js
  • javascript
  • output
  • rst
  • rest
  • shell
  • php
  • sql
  • sh
  • bash
  • tsconfig
  • ts
  • typescript
  • typoscript
  • xml
  • yaml

Standard Sphinx interpreted text roles 

See also: Standard Sphinx interpreted text roles

Role Source Output Note
abbr :abbr:`LIFO (last-in, first-out)` LIFO An abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX.
code :code:`result = (1 + x) * 32` result = (1 + x) * 32  
command :command:`rm` rm The name of an OS-level command, such as rm.
dfn :dfn:`something` something Mark the defining instance of a term in the text. (No index entries are generated.)
file :file:`/etc/passwd` /etc/passwd  
guilabel :guilabel:`&Cancel`, :guilabel:`O&k`, :guilabel:`&Reset`, :guilabel:`F&&Q` &Cancel, O&k, &Reset, F&&Q Labels presented as part of an interactive user interface should be marked using guilabel. This includes labels from text-based interfaces such as those created using curses or other text-based libraries. Any label used in the interface should be marked with this role, including button labels, window titles, field names, menu and menu selection names, and even values in selection lists.
kbd Press :kbd:`ctrl` + :kbd:`s` Press ctrl + s Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like C + :kbdx, C + f, but without reference to a specific application or platform, the same sequence should be marked as ctrl + x, ctrl + f.
mailheader :mailheader:`Content-Type` Content-Type The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.” This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage.
term :term:`CMS`, :term:`cms`, :term:`magic number`, :term:`term text role` CMS, cms, magic number, term text role Reference the term of a glossary
ref :ref:`Inline-Code` Inline code and text roles Sphinx cross-referencing

Standard Docutils interpreted text roles 

See also: Standard Docutils interpreted text roles

Role Source Output Note
emphasis :emphasis:`text`, *text* text, text  
literal :literal:`\ \ abc` \ \ abc  
literal :literal:`text`, ''text'' (backticks!) text, text  
math :math:`A_\text{c} = (\pi/4) d^2` A_\text{c} = (\pi/4) d^2 The math role marks its content as mathematical notation (inline formula). The input format is LaTeX math syntax without the “math delimiters“ ($ $).
rfc, rfc-reference :RFC:`2822` 2822  
strong :strong:`text`, **text** text, text Implements strong emphasis.
subscript :subscript:`subscripted` subscripted  
superscript :superscript:`superscripted` superscripted  
t, title-reference :t:`Design Patterns` Design Patterns The :title-reference: role is used to describe the titles of books, periodicals, and other materials.

A glossary and the :term: textrole 

Glossary to define some demo terms

This is a small demo glossary to allow the :term: text role in the above examples.

C

CMS

Content management system
M

magic number

A magic number is a magic number.
T

term text role

The :term: texrole is used to create crossreferences to terms of the glossary.

Example: "Refer to our glossary to find out about CMS or magic number or term text role".

Some really long inline text 

Now, let's see what happens when you have some really long inline text like $GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations'] ['rootline']['backend'] = \TYPO3\CMS\Core\Cache\Backend\ApcuBackend::class; How does it show up?

Older stuff - needs cleaning up 

role source output
(default) `result = (1 + x) * 32` result = (1 + x) * 32
aspect :aspect:`Description:` Description:
code :code:`result = (1 + x) * 32` result = (1 + x) * 32
file :file:`/etc/passwd` /etc/passwd
js :js:`var f = function () {return 1;}` var f = function () {return 1;}
html :html:`<a href="#">` <a href="#">
ts :ts:`lib.hello.value = Hello World!` lib.hello.value = Hello World!
typoscript :typoscript:`lib.hello.value = Hello World!` lib.hello.value = Hello World!
php :php:`$result = $a + 23;` $result = $a + 23;

Standard Sphinx and Docutils Textroles 

  • This is how :code:`result = (1 + x) * 32` looks like: result = (1 + x) * 32
  • "code" also is the default text-role. So `result = (1 + x) * 32` looks the same result = (1 + x) * 32 as :code:`result = (1 + x) * 32`.
  • This is how :file:`/etc/passwd` looks like: /etc/passwd

Self Defined Textroles 

In file /Includes.rst.txt we usually have:

.. This is '/Includes.rst.txt'. It is included at the very top of each
   and every ReST source file in THIS documentation project (= manual).

.. role:: aspect (emphasis)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: typoscript(code)
.. role:: ts(typoscript)
   :class: typoscript

.. highlight:: php
.. default-role:: code
Copied!

Check the following to see if we have give those an individual styling:

  • This is how :php:`$result = $a + 23;` looks like: $result = $a + 23;
  • This is how :typoscript:`lib.hello.value = Hello World!` looks like: lib.hello.value = Hello World!
  • This is how :ts:`lib.hello.value = Hello World!` looks like: lib.hello.value = Hello World!

Inline code MyCustomException PAGE in title 

Inline code MyCustomException PAGE in title 

Inline code MyCustomException PAGE in title 

Inline code MyCustomException PAGE in title 
Inline code MyCustomException PAGE in title 

Fully qualified names with backslashes 

Source:

:code:`TYPO3\CMS\Core\Cache\Frontend\FrontendInterface`

:php:`TYPO3\CMS\Core\Cache\Frontend\FrontendInterface`

`TYPO3\CMS\Core\Cache\Frontend\FrontendInterface`

``TYPO3\CMS\Core\Cache\Frontend\FrontendInterface``
Copied!

Result:

TYPO3\CMS\Core\Cache\Frontend\FrontendInterface

\TYPO3\CMS\Core\Cache\Frontend\FrontendInterface

TYPO3\CMS\Core\Cache\Frontend\FrontendInterface

TYPO3\CMS\Core\Cache\Frontend\FrontendInterface