diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/usage/restructuredtext/directives.rst | 6 | ||||
-rw-r--r-- | doc/usage/restructuredtext/roles.rst | 28 |
2 files changed, 32 insertions, 2 deletions
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index d1877bca0..847f0372b 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -499,8 +499,10 @@ __ https://pygments.org/docs/lexers The directive's alias name :rst:dir:`sourcecode` works as well. This directive takes a language name as an argument. It can be `any lexer alias supported by Pygments <https://pygments.org/docs/lexers/>`_. If it is not - given, the setting of :rst:dir:`highlight` directive will be used. - If not set, :confval:`highlight_language` will be used. + given, the setting of :rst:dir:`highlight` directive will be used. If not + set, :confval:`highlight_language` will be used. To display a code example + *inline* within other text, rather than as a separate block, you can use the + :rst:role:`code` role instead. .. versionchanged:: 2.0 The ``language`` argument becomes optional. diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index de12a41b5..9d790b30e 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -276,6 +276,34 @@ The following role creates a cross-reference to a term in a If you use a term that's not explained in a glossary, you'll get a warning during build. +Inline code highlighting +------------------------ + +.. rst:role:: code + + An *inline* code example. When used directly, this role just displays the + text *without* syntax highlighting, as a literal. + + .. code-block:: rst + + By default, inline code such as :code:`1 + 2` just displays without + highlighting. + + Unlike the :rst:dir:`code-block` directive, this role does not respect the + default language set by the :rst:dir:`highlight` directive. + + To enable syntax highlighting, you must first use the ``role`` directive to + define a custom ``code`` role for a particular language: + + .. code-block:: rst + + .. role:: python(code) + :language: python + + In Python, :python:`1 + 2` is equal to :python:`3`. + + To display a multi-line code example, use the :rst:dir:`code-block` directive + instead. Math ---- |