Code syntax highlighting
========================

.. rst:directive:: .. default-literal-role:: role

   Sets the default literal role generated by double backticks literal syntax.

   Normally, double backticks:

   .. code-block:: rst

      ``abc``

   is equivalent to the :durole:`literal` role:

   .. code-block:: rst

      :literal:`abc`

   This directive causes the double backticks syntax to instead generate the
   specified role.  Invoking the directive with no argument resets the literal
   role back to the default of :durole:`literal`.

   .. rst-example:: Changing the literal role

      Normal literal role: ``1 + 2``

      .. default-literal-role:: python

      Python literal role: ``1 + 2``

      .. default-literal-role::

      Normal literal role again: ``1 + 2``

.. rst:directive:: highlight-push

   Saves the current :rst:dir:`highlight` settings.  The saved settings can be
   restored using the :rst:dir:`highlight-pop` directive.

   .. rst-example:: Temporarily changing the highlight language

      .. highlight-push::

      .. highlight:: json

      The following literal block will be highlighted as JSON::

         {"a": 10, "b": null, "c": 10}

      .. highlight-push::

      .. highlight:: python

      The following block will be highlighted as Python::

         def foo(x: int) -> None: ...

      .. highlight-pop::

      The following block will be highlighted as JSON::

         [1, 2, true, false]

.. rst:directive:: highlight-pop

   Restores the :rst:dir:`highlight` settings saved by a prior invocation of
   :rst:dir:`highlight-push`.
