Repository: PlasmaPy/PlasmaPy

Issue:
Enable inline code highlighting via Sphinx 5.0.0
Sphinx 5.0.0 was released today, and it turns out that it's now possible to have [inline code syntax highlighting](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting) (!!!!!) just like in `code-block` directives.  This change would require making a new role for reStructuredText, so it wouldn't automagically get applied to code snippets with double back ticks. This change would probably make us require `sphinx >= 5.0.0`, and since this release is only a few hours old, and my inclination would be to make this change after our 0.8.0 release.

 - [ ] Add new role (`:py:` or `:python:`?) to [`rst_prolog`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog) in `docs/conf.py` (which is similar to [`rst_epilog`](https://github.com/PlasmaPy/PlasmaPy/blob/1b9238439c1e4a7c1d35b8f812b4805872f0aae6/docs/conf.py#L187) but would need to be defined).
 - [ ] Describe this capability in the documentation guide
 - [ ] Update the requirements to `sphinx >= 5.0.0`




Discussion:

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -80,7 +80,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 
-needs_sphinx = "4.4"
+needs_sphinx = "5.0.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -173,6 +173,7 @@
 project = "PlasmaPy"
 author = "PlasmaPy Community"
 copyright = f"2015–{datetime.utcnow().year}, {author}"
+language = "en"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -194,12 +195,10 @@
 with open("common_links.rst") as cl:
     rst_epilog += cl.read()
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = "en"
+rst_prolog = """
+.. role:: py(code)
+   :language: python
+"""
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -383,9 +382,6 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
-# html_theme = 'traditional'
-# html_theme = 'agogo'
 html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme


Test patch:
diff --git a/docs/contributing/testing_guide.rst b/docs/contributing/testing_guide.rst
--- a/docs/contributing/testing_guide.rst
+++ b/docs/contributing/testing_guide.rst
@@ -460,7 +460,7 @@ both will be run.
 However, this approach can lead to cumbersome, repeated code if you are
 calling the same function over and over. If you wish to run multiple
 tests for the same function, the preferred method is to decorate it with
-``@pytest.mark.parametrize``.
+:py:`@pytest.mark.parametrize`.
 
 .. code-block:: python
 
@@ -468,8 +468,8 @@ tests for the same function, the preferred method is to decorate it with
    def test_proof_if_riemann(truth_value):
         assert proof_by_riemann(truth_value)
 
-This code snippet will run ``proof_by_riemann(truth_value)`` for each
-``truth_value`` in ``[True, False]``. Both of the above
+This code snippet will run :py:`proof_by_riemann(truth_value)` for each
+``truth_value`` in :py:`[True, False]`. Both of the above
 tests will be run regardless of failures. This approach is much cleaner
 for long lists of arguments, and has the advantage that you would only
 need to change the function call in one place if the function changes.
@@ -549,7 +549,7 @@ Property-based testing
 ----------------------
 
 Suppose a function :math:`f(x)` has a property that :math:`f(x) > 0` for
-all :math:`x`. A property-based test would verify that ``f(x)`` — the
+all :math:`x`. A property-based test would verify that :py:`f(x)` — the
 code implementation of :math:`f(x)` — returns positive output for
 multiple values of :math:`x`. The hypothesis_ package simplifies
 `property-based testing`_ for Python.
@@ -660,7 +660,7 @@ should be balanced with each other rather than absolute principles.
   increases the probability that we will lose track of what we are
   doing and slows down progress.
 
-  Decorate unavoidably slow tests with ``@pytest.mark.slow``:
+  Decorate unavoidably slow tests with :py:`@pytest.mark.slow`:
 
   .. code-block:: python