******************
Sphinx Code Blocks
******************

Sphinx has its own custom code-block directive, which you should use instead of the

::

    .. code::

directive because it has more reliable code highlighting and a VERY LARGE array of
supported languages documented here:  https://pygments.org/docs/lexers/ .  Its
syntax is:

::

    .. code-block:: [language]

where [language] is optionally replaced with one of the languages listed under the
`Pygments package lexers`_.

.. note::
    According to https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
    Sphinx also applies the same logic to the ``.. code::`` directivie, so the above
    statement may be incorrect about it being "more reliable".  I heard that from
    someone reporting it on a forum, so I don't know what he did, or how long the
    ``.. code::`` directive has been listed as a synonym for the ``.. code-block::``
    directive.



.. include:: external_links.txt