Repository: PlasmaPy/PlasmaPy

Issue:
Enable `:issue:` and `:pr:` roles in documentation
@rocco8773 found [sphinx-issues](https://github.com/sloria/sphinx-issues) which is a Sphinx extension that enables the `:issue:` and `:pr:` roles for referencing issues and PRs in our repository, plus a few others like `:user:` and `:commit:`.  It would be good to enable these roles, likely through enabling sphinx-issues.  When considering that, we should look into how well-maintained this extension is.


Discussion:

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -74,30 +74,36 @@
 )
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+
+needs_sphinx = "4.4"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones. When extensions are removed or added, please update the section
 # in docs/doc_guide.rst on Sphinx extensions.
+
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
+    "sphinx.ext.extlinks",
     "sphinx.ext.graphviz",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "nbsphinx",
+    "sphinxcontrib.bibtex",
     "sphinx_copybutton",
     "sphinx_gallery.load_style",
     "IPython.sphinxext.ipython_console_highlighting",
     "sphinx_changelog",
-    "plasmapy_sphinx",
-    "sphinxcontrib.bibtex",
     "hoverxref.extension",
+    "notfound.extension",
+    "sphinx_issues",
+    "plasmapy_sphinx",
 ]
 
+# Configure sphinxcontrib-bibtex
+
 bibtex_bibfiles = ["bibliography.bib"]
 bibtex_default_style = "plain"
 bibtex_reference_style = "author_year"
@@ -105,6 +111,7 @@
 # Intersphinx generates automatic links to the documentation of objects
 # in other packages. When mappings are removed or added, please update
 # the section in docs/doc_guide.rst on references to other packages.
+
 intersphinx_mapping = {
     "readthedocs": ("https://docs.readthedocs.io/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
@@ -137,6 +144,10 @@
 autoclass_content = "both"
 autodoc_typehints_format = "short"
 
+# Configure sphinx-issues
+
+issues_github_path = "PlasmaPy/PlasmaPy"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -166,10 +177,7 @@
 pv = parse_version(release)
 release = pv.public
 version = ".".join(release.split(".")[:2])  # short X.Y version
-if pv.local is not None:
-    revision = pv.local[1:]  # revision number w/o the leading g
-else:
-    revision = ""
+revision = pv.local[1:] if pv.local is not None else ""
 
 # This is added to the end of RST files — a good place to put substitutions to
 # be used globally.
@@ -195,6 +203,7 @@
     "**.ipynb_checkpoints",
     "plasmapy_sphinx",
     "common_links.rst",
+    "**Untitled*",
 ]
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
@@ -203,12 +212,14 @@
 default_role = "py:obj"
 
 # Customizations for make linkcheck using regular expressions
+
 linkcheck_allowed_redirects = {
     r"https://doi\.org/.+": r"https://.+",  # DOI links are more persistent
     r"https://docs.+\.org": r"https://docs.+\.org/en/.+",
     r"https://docs.+\.io": r"https://docs.+\.io/en/.+",
     r"https://docs.+\.com": r"https://docs.+\.com/en/.+",
     r"https://docs.+\.dev": r"https://docs.+\.dev/en/.+",
+    r"https://en.wikipedia.org/wiki.+": "https://en.wikipedia.org/wiki.+",
     r"https://.+\.readthedocs\.io": r"https://.+\.readthedocs\.io/en/.+",
     r"https://www\.sphinx-doc\.org": r"https://www\.sphinx-doc\.org/en/.+",
     r"https://.+/github\.io": r"https://.+/github\.io/en/.+",
@@ -272,6 +283,19 @@
     "term": "tooltip",
 }
 
+# Using sphinx.ext.extlinks lets us simplify the process of creating
+# links to commonly used external sites. The key of the extlink becomes
+# a new role, and the corresponding tuple contains the base url and the
+# caption. For example, we can now do :orcid:`0000-0000-0000-0000` and
+# have a link create to the corresponding ORCID page. New roles should
+# be added to rst-roles in setup.cfg to avoid being caught by
+# flake8-rst-docstrings.
+
+extlinks = {
+    "orcid": ("https://orcid.org/%s", "%s"),
+    "wikipedia": ("https://en.wikipedia.org/wiki/", "%s"),
+}
+
 # Specify patterns to ignore when doing a nitpicky documentation build.
 # These may include common expressions like "real number" as well as
 # workarounds for nested inline literals as defined in docs/common_links.py
@@ -296,7 +320,7 @@
     (python_role, ".*real number.*"),
     (python_role, ".*representation.*"),
     (python_role, "shape.*"),
-    (python_role, "u\..*"),
+    (python_role, r"u\..*"),
     (python_role, ".*Unit.*"),
     # pytest helpers
     (python_role, "_pytest.*"),


Test patch:
diff --git a/docs/development/testing_guide.rst b/docs/development/testing_guide.rst
--- a/docs/development/testing_guide.rst
+++ b/docs/development/testing_guide.rst
@@ -55,7 +55,8 @@ PlasmaPy's tests can be run in the following ways:
 1. Creating and updating a pull request on GitHub_.
 2. Running pytest_ from the command line.
 3. Running tox_ from the command line.
-4. Running tests from an `integrated development environment`_ (IDE).
+4. Running tests from an :wikipedia:`integrated development environment
+   <integrated_development_environment>` (IDE).
 
 We recommend that new contributors perform the tests via a pull request
 on GitHub_. Creating a draft pull request and keeping it updated will
@@ -417,8 +418,7 @@ Test independence and parametrization
 -------------------------------------
 
 In this section, we'll discuss the issue of parametrization based on
-an example of a `proof
-<https://en.wikipedia.org/wiki/Riemann\_hypothesis#Excluded\_middle>`_
+an example of a :wikipedia:`proof <Riemann_hypothesis#Excluded_middle>`
 of Gauss's class number conjecture.
 
 The proof goes along these lines:
@@ -554,9 +554,10 @@ multiple values of :math:`x`. The hypothesis_ package simplifies
 Code coverage
 =============
 
-`Code coverage`_ refers to a metric "used to describe the degree to
-which the source code of a program is executed when a particular test
-suite runs." The most common code coverage metric is line coverage:
+:wikipedia:`Code coverage <Code_coverage>` refers to a metric "used to
+describe the degree to which the source code of a program is executed
+when a particular test suite runs." The most common code coverage metric
+is line coverage:
 
 .. math::
 
@@ -675,9 +676,10 @@ should be balanced with each other rather than absolute principles.
 * **Write code that is easy to test.** Write short functions that do
   exactly one thing with no side effects. Break up long functions into
   multiple functions that are smaller and more focused. Use
-  `pure functions`_ rather than functions that change the underlying
-  state of the system or depend on non-local variables. Use
-  `test-driven development`_ and write tests before writing the code to
+  :wikipedia:`pure functions <pure_function>` rather than functions that
+  change the underlying state of the system or depend on non-local
+  variables. Use :wikipedia:`test-driven development
+  <Test-driven_development>` and write tests before writing the code to
   be tested. When a section of code is difficult to test, consider
   refactoring_ it to make it easier to test.
 
@@ -730,7 +732,6 @@ should be balanced with each other rather than absolute principles.
 
 .. _Atom: https://atom.io
 .. _Codecov: https://about.codecov.io
-.. _`code coverage`: https://en.wikipedia.org/wiki/Code_coverage
 .. _codespell: https://github.com/codespell-project/codespell
 .. _`coverage.py`: https://coverage.readthedocs.io
 .. _`create a pull request`: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests
@@ -739,16 +740,13 @@ should be balanced with each other rather than absolute principles.
 .. _`grouped into classes`: https://docs.pytest.org/en/latest/getting-started.html#group-multiple-tests-in-a-class
 .. _`how to invoke pytest`: https://docs.pytest.org/en/latest/how-to/usage.html
 .. _hypothesis: https://hypothesis.readthedocs.io
-.. _`integrated development environment`: https://en.wikipedia.org/wiki/Integrated_development_environment
 .. _`property-based testing`: https://hypothesis.works/articles/what-is-hypothesis
-.. _`pure functions`: https://en.wikipedia.org/wiki/Pure_function
 .. _PyCharm: https://www.jetbrains.com/pycharm
 .. _pytest: https://docs.pytest.org
 .. _`pytest-cov`: https://pytest-cov.readthedocs.io
 .. _`Python debugger`: https://docs.python.org/3/library/pdb.html
 .. _refactoring: https://refactoring.guru/refactoring/techniques
 .. _`test discovery conventions`: https://docs.pytest.org/en/latest/goodpractices.html#conventions-for-python-test-discovery
-.. _`test-driven development`: https://en.wikipedia.org/wiki/Test-driven_development
 .. _`test warnings`: https://docs.pytest.org/en/latest/warnings.html#warns
 .. _`test exceptions`: https://docs.pytest.org/en/latest/assert.html#assertions-about-expected-exceptions
 .. _`tox environments`: https://tox.wiki/en/latest/config.html#tox-environments