Repository: PlasmaPy/PlasmaPy

Issue:
Edit gyroradius function to better indicate that it's not just for ions
`plasmapy.formulary.gyroradius` has some code within it that indicates that the particle should be an ion.  In particular, one of the inputs is `T_i`.  We should change the code and documentation to show make it more general (i.e. changing `T_i` to `T`).  This would be a backwards incompatible change so we would probably want to put a deprecation warning for `T_i` and let `T_i` continue to be used for one more release.  

This issue is similar to and a bit more complex than #1169. 

Discussion:
RAJAGOPALAN-GANGADHARAN: Could someone please give this PR a review.

Patch:
diff --git a/changelog/1156.doc.rst b/changelog/1156.doc.rst
new file mode 100644
index 00000000..62116bf3
--- /dev/null
+++ b/changelog/1156.doc.rst
@@ -0,0 +1,2 @@
+Updated information on how to write and build documentation in the
+development guide.
diff --git a/changelog/1195.trivial.rst b/changelog/1195.trivial.rst
index d7eb574f..d6a8edbf 100644
--- a/changelog/1195.trivial.rst
+++ b/changelog/1195.trivial.rst
@@ -1,2 +1,2 @@
-Added `tox <https://tox.readthedocs.io/en/latest/>`_ and removed
-`pytest <https://docs.pytest.org/>`_ as extra requirements.
+Added tox_ and removed `pytest <https://docs.pytest.org/>`_ as extra
+requirements.
diff --git a/changelog/1210.removal.rst b/changelog/1210.removal.rst
new file mode 100644
index 00000000..e66bbf70
--- /dev/null
+++ b/changelog/1210.removal.rst
@@ -0,0 +1,2 @@
+Use more generalized keyword argument ``T`` instead of ``T_i`` in `plasmapy.formulary.parameters.gyroradius`.
+The ``T_i`` argument has been deprecated and will be removed in a subsequent release.
diff --git a/docs/about/credits.rst b/docs/about/credits.rst
index c2575632..6734612c 100644
--- a/docs/about/credits.rst
+++ b/docs/about/credits.rst
@@ -7,7 +7,6 @@ PlasmaPy Coordinating Committee
 
 * Erik Everson
 * Nicholas Murphy
-* Tulasi Parashar
 * Dominik Stańczak
 
 PlasmaPy Contributors
diff --git a/docs/common_links.rst b/docs/common_links.rst
index 3e7f7213..000ddb3a 100644
--- a/docs/common_links.rst
+++ b/docs/common_links.rst
@@ -35,26 +35,37 @@
 .. Astropy replacements
 .. --------------------
 
-.. |PhysicalType| replace:: :class:`~astropy.units.PhysicalType`
 .. |Quantity| replace:: :class:`~astropy.units.Quantity`
 .. |Time| replace:: :class:`~astropy.time.Time`
 .. |TimeDelta| replace:: :class:`~astropy.time.TimeDelta`
 .. |Unit| replace:: :class:`~astropy.units.UnitBase`
 
-.. -----------------
-.. Links to Packages
-.. -----------------
+.. --------
+.. Websites
+.. --------
 
 .. _Astropy: https://www.astropy.org/
 .. _`Astropy docs`: https://docs.astropy.org/
+.. _`docs/common_links.rst`: https://github.com/PlasmaPy/PlasmaPy/blob/main/docs/common_links.rst
 .. _Conda: https://conda.io/docs/
 .. _git: https://git-scm.com/
+.. _intersphinx: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
+.. _Jupyter: https://jupyter.org/
+.. _Markdown: https://www.markdownguide.org/
 .. _matplotlib: https://matplotlib.org/
 .. _NumPy: https://numpy.org/
-.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
+.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 .. _pip: https://pip.pypa.io
+.. _`PlasmaPy's GitHub repository`: https://github.com/PlasmaPy/plasmapy
+.. _`PlasmaPy's documentation`: https://docs.plasmapy.org/en/stable/
 .. _PyPI: https://pypi.org/
 .. _Python: https://www.python.org/
+.. _`Python's documentation`: https://docs.python.org/
+.. _`Read the Docs`: https://readthedocs.org/
+.. _reST: https://docutils.sourceforge.io/rst.html
 .. _SciPy: https://www.scipy.org/
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _towncrier: https://towncrier.readthedocs.io/en/actual-freaking-docs/
+.. _tox: https://tox.readthedocs.io/
 .. _virtualenv: https://pypi.org/project/virtualenv
 .. _Zenodo: https://zenodo.org
diff --git a/docs/conf.py b/docs/conf.py
index eefb82c0..42789c40 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -54,7 +54,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# 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",
@@ -70,6 +71,9 @@
     "plasmapy_sphinx",
 ]
 
+# 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 = {
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
diff --git a/docs/development/doc_guide.rst b/docs/development/doc_guide.rst
index e432dc86..2f9ebfb1 100644
--- a/docs/development/doc_guide.rst
+++ b/docs/development/doc_guide.rst
@@ -1,76 +1,889 @@
-************************
-Documentation Guidelines
-************************
+*******************
+Documentation Guide
+*******************
 
-This document describes the documentation requirements and guidelines
-to be followed during the development of PlasmaPy and affiliated
-packages.
+Documentation that is up-to-date and understandable is vital to the
+health of a software project. This page describes the documentation
+requirements and guidelines to be followed during the development of
+PlasmaPy and affiliated packages.
+
+.. tip::
+
+   Updating documentation is one of the best ways to make a first
+   contribution to an open source software project.
+
+.. note::
+
+   If you discover areas within PlasmaPy's documentation that are
+   confusing or incomplete, please `raise an issue`_! This really helps
+   PlasmaPy not only by helping us improve the documentation for all,
+   but also by creating opportunities for new contributors to make their
+   first contribution to the project.
+
+`PlasmaPy's documentation`_ is hosted by `Read the Docs`_ and is
+available at these locations:
+
+* The documentation corresponding to the most recent release to PyPI_ is
+  labelled ``stable`` and is found at `https://docs.plasmapy.org/`_ or
+  `https://docs.plasmapy.org/en/stable/`_.
+
+* The documentation corresponding to the ongoing development on the
+  ``main`` branch in `PlasmaPy's GitHub repository`_ , which is often ahead
+  of the most recent release, is labelled ``latest`` and can be found at
+  `https://docs.plasmapy.org/en/latest/`_.
+
+.. tip::
+
+  A preview of the documentation is generated every time a pull request
+  is created or updated. You can access this preview by scrolling down
+  to the checks at the bottom of a pull request, and clicking on
+  ``Details`` next to ``docs/readthedocs.org:plasmapy``.
 
 Building documentation
 ======================
-Documentation is built from the main branch on every commit pushed
-to it.
 
-Sphinx, the documentation generator of PlasmaPy, uses reStructuredText (reST) as its markup language. A primer on reST is available at this `webpage
-<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
-of Sphinx's website.
+There are two methods for building the documentation: make_ and tox_.
+
+* Using make_ will build the documentation based off of what is in the
+  current directory structure. make_ is quicker for local builds than
+  tox_ but requires you to install and setup all dependencies.
+* Using tox_ does not require setting up all dependencies ahead of time,
+  but is more computationally intensive since it creates a virtual
+  environment and builds the package before building the documentation.
+  Consequently, PlasmaPy uses tox_ for building the documentation on
+  continuous integration testing platforms.
+
+Prerequisites
+-------------
+
+To install all dependencies required to develop PlasmaPy on your local
+computer, enter the top-level directory of the cloned repository and
+run:
+
+.. code-block:: bash
+
+   pip install -r requirements.txt
 
-Using sphinx within the project
+Building documentation with make
+--------------------------------
+
+If you have make_ installed, then you can build the documentation by
+entering the :file:`docs/` directory and running:
+
+.. code-block:: bash
+
+   make html
+
+Including the ``-j n`` flag in the ``make`` command will enable a
+parallel build, where ``n`` is replaced with the number of processes.
+
+You can access the documentation landing page by opening
+:file:`docs/_build/html/index.html` with your browser of choice.
+
+To remove all files previously generated by ``make``, run:
+
+.. code-block:: bash
+
+   make clean
+
+This command is needed when you make a change to a file that does not
+trigger Sphinx_ to rebuild the file that you altered, for example
+modifying a CSS_ file.
+
+Building documentation with tox
 -------------------------------
-To build docs locally, either:
 
-* use `Tox <https://tox.readthedocs.io/en/latest/>`_ with ``tox -e build_docs`` from within the main PlasmaPy repository directory, or
-* enter the ``docs`` directory and run ``make html``.
+You can use tox_ to locally build the documentation by running:
 
-Afterwards, open ``docs/_build/html/index.html`` with your browser of choice.
+.. code-block:: bash
 
-Do try to solve warnings in documentation when writing your code. To enforce this,
-The ``build_docs`` environment is set to fail on encountering any warnings via
-the ``-W`` flag to ``sphinx-build``
+   tox -e build_docs
 
-.. note::
-   The ``tox -e build_docs_no_examples`` command will build the documentation without
-   executing the :ref:`example notebooks <example_notebooks>`. It will also
-   pass with warnings.
+You can access the documentation landing page by opening
+:file:`docs/_build/html/index.html` with your browser of choice.
+
+When writing documentation, please make sure to fix any warnings that
+arise. To enforce this, the ``build_docs`` environment is set to fail on
+encountering any warnings via the ``-W`` flag to `sphinx-build`_.
+
+You can shorten the tox_ documentation build by running:
+
+.. code-block:: bash
+
+   tox -e build_docs_no_examples
+
+in order to build the documentation without executing the :ref:`example
+notebooks <example_notebooks>`. This command will pass even if there are
+warnings. A tox_ command may also include the ``--parallel`` flag to
+allow a parallel build.
+
+Documentation tools
+===================
+
+ReStructuredText
+----------------
+
+PlasmaPy's documentation is written using the `reStructuredText (reST)`_
+markup language. reST_ is human readable when viewed within a source
+code file or when printed out using `help`. reST_ also contains markup
+that allows the text to be transformed into `PlasmaPy's documentation`_.
+reST_ files use the file extension :file:`.rst`. Documentation contained
+within :file:`.py` files are in the form of docstrings_, which are
+written in reST_.
+
+ReStructuredText Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here we show some examples of commonly used reST_ syntax in
+PlasmaPy. Please refer to the documentation for Sphinx_ and reST_ for a
+list of available directives and syntax.
+
+This is an example of including headings for the document title,
+sections, subsections, and so on. The lines surrounding each heading are
+the same length as that heading.
+
+.. code-block:: rst
+
+   ==============
+   Document title
+   ==============
+
+   Heading 1
+   =========
+
+   Heading 2
+   ---------
+
+   Heading 3
+   ~~~~~~~~~
+
+We can link to code objects by enclosing them in single back ticks.
+This linking will work for Python_ commands as well as certain packages
+like NumPy_, SciPy_, Astropy_, and pandas_. This linking is described in
+the section on :ref:`external-references`. In-line code examples are
+enclosed in double back ticks.
+
+.. code-block:: rst
+
+   Here `plasmapy.particles` provides a linked reference to the
+   module's documentation.
+
+   Adding a tilde at the beginning `~plasmapy.particles` still
+   provides a linked reference to the associated documentation
+   but shortens the display so only "particles" is displayed.
+
+   Double backticks are used to show inline code that is not
+   cross-referenced: ``import astropy.units as u``.
+
+This reST_ block renders as:
+
+   Here `plasmapy.particles` provides a linked reference to the
+   module's documentation.
+
+   Adding a tilde at the beginning `~plasmapy.particles` still
+   provides a linked reference to the associated documentation
+   but shortens the display so only "particles" is displayed.
+
+   Double backticks are used to show inline code that is not
+   cross-referenced: ``import astropy.units as u``.
+
+Sphinx_ can format code blocks for Python_ and the Python_ console.
+
+   .. code-block:: rst
+
+      .. code-block:: python
+
+         def sample_function():
+             return 42
+
+      .. code-block:: pycon
+
+         >>> print(6 * 9)
+         54
+
+This reST block renders as:
+
+   .. code-block:: python
+
+      def sample_function():
+          return 42
+
+   .. code-block:: pycon
+
+      >>> print(6 * 9)
+      54
+
+Here are some examples for linking to websites.
+
+.. code-block:: rst
+
+   `PlasmaPy Enhancement Proposals <https://github.com/PlasmaPy/PlasmaPy-PLEPs>`_
+   are used to propose major changes to PlasmaPy.
+
+   `Write the Docs`_ has a guide_ on writing software documentation.
+
+   .. _`Write the Docs`: https://www.writethedocs.org/
+   .. _guide: https://www.writethedocs.org/
+
+This reST_ block renders as:
+
+   `PlasmaPy Enhancement Proposals <https://github.com/PlasmaPy/PlasmaPy-PLEPs>`_
+   are used to propose major changes to PlasmaPy.
+
+   `Write the Docs`_ has a guide_ on writing software documentation.
+
+   .. _`Write the Docs`: https://www.writethedocs.org/
+   .. _guide: https://www.writethedocs.org/
+
+Math can typically be written using LaTeX_ commands.
+
+.. code-block:: rst
+
+   .. math::
+
+      \alpha = \beta + \gamma
+
+This reST_ block renders as:
+
+   .. math::
+
+      \alpha = \beta + \gamma
+
+Math can be in-line.
+
+.. code-block:: rst
+
+   An example of in-line math is :math:`x`. Using Unicode characters
+   like :math:`α + β + γ` makes math easier to read in the source code.
+
+This reST_ block renders as:
+
+   An example of in-line math is :math:`x`. Using Unicode characters
+   like :math:`α + β + γ` makes math easier to read in the source code.
+
+Markdown
+--------
+
+A few of PlasmaPy's files are written using Markdown_, such as README
+files and licenses from other packages. Markdown_ is simpler but more
+limited than reST_. Markdown_ files use the file extension :file:`.md`.
+Posts on GitHub are written in `GitHub Flavored Markdown`_. The
+following code block contains a few common examples of Markdown_
+formatting.
+
+.. code-block:: markdown
+
+   # Header 1
+
+   ## Header 2
+
+   Here is a link to [PlasmaPy's documentation](https://docs.plasmapy.org).
+
+   We can make text **bold** or *italic*.
+
+   We can write in-line code like `x = 1` or create a Python code block:
+
+   ```Python
+   y = 2
+   z = 3
+   ```
+
+Sphinx
+------
+
+Sphinx_ is the software used to generate `PlasmaPy's documentation`_
+from reST_ files and Python_ docstrings. It was originally created to
+write Python's documentation and has become the de facto software for
+documenting Python_ packages. Almost all Python_ open-source packages
+utilize Sphinx_ to generate their documentation.
+
+Configuration
+~~~~~~~~~~~~~
+
+The `docs/conf.py`_ file contains the configuration information needed
+to customize Sphinx_ behavior. The documentation for Sphinx_ lists the
+`configuration options`_ that can be set.
+
+The `docs/_static/sphinx_rtd_overrides.css`_ file contains `style
+overrides`_ for the `Read the Docs Sphinx Theme`_ to customize the look
+and feel of the online documentation.
+
+Sphinx extensions
+~~~~~~~~~~~~~~~~~
+
+`PlasmaPy's documentation`_ is built with the following Sphinx_
+extensions:
+
+* `sphinx.ext.autodoc` for including documentation from docstrings
+* `sphinx.ext.intersphinx` for linking to other projects' documentation
+* `sphinx.ext.graphviz` to allow Graphviz_ graphs to be included
+* `sphinx.ext.mathjax` for math rendering with MathJax_
+* `sphinx.ext.napoleon` for allowing NumPy style docstrings
+* `sphinx.ext.todo` to support ``todo`` directives
+* nbsphinx_ for including Jupyter_ notebooks
+* `sphinx_copybutton`_ to add a "copy" button for code blocks
+* `sphinx_gallery.load_style`_ for using sphinx-gallery styles
+* `IPython.sphinxext.ipython_console_highlighting`_
+* `sphinx_changelog`_ for rendering `towncrier`_ changelogs
+* `plasmapy_sphinx` for customizations created for use in PlasmaPy and
+  affiliated packages. Note that `plasmapy_sphinx` is expected to be
+  broken out into its own package in the future.
+
+These extensions are specified in :confval:`extensions` configuration
+value in `docs/conf.py`_.
+
+.. _external-references:
+
+Cross-referencing external packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Intersphinx_ allows the automatic generation of links to the
+documentation of objects in other projects. This cross-package linking
+is made possible with the `sphinx.ext.intersphinx` extension and proper
+package indexing by the external package using `sphinx.ext.autodoc`.
+
+When we include ```astropy.units.Quantity``` in the documentation, it
+will show up as `astropy.units.Quantity` with a link to the appropriate
+page in Astropy documentation. Similarly, ```~astropy.units.Quantity```
+will show up as `~astropy.units.Quantity`.
+
+To make cross-referencing to an external package available its
+mappings have to be defined in the :confval:`intersphinx_mapping`
+configuration dictionary contained in `docs/conf.py`_. PlasmaPy
+has already include several packages like Python_, NumPy_, SciPy_,
+Astropy_, Sphinx_, etc.
+
+New source packages may be added, but please verify that references to a
+function or class in that package show up correctly in `PlasmaPy's
+documentation`_. The name of the package does not always link as
+expected.
+
+.. hint::
+
+   If a cross-link is not working as expected this is usually due to one
+   of the following reasons:
+
+   * A typo;
+   * The package not being defined in :confval:`intersphinx_mapping`, or
+   * The referenced source package not properly or fully indexing their
+     own code, which is common in Python_ packages.
+
+Substitutions
+~~~~~~~~~~~~~
+
+Some functions and classes are referred to repeatedly throughout the
+documentation. reST_ allows us to `define substitutions`_
+
+.. code-block:: rst
+
+   .. |Particle| replace:: `~plasmapy.particles.particle_class.Particle`
+
+Here whenever ``|Particle|`` is used Sphinx_ will replace it with
+```~plasmapy.particles.particle_class.Particle``` during build time.
+
+PlasmaPy has certain common substitutions pre-defined so that they can
+be used elsewhere in the documentation. For example, we can write
+``|Quantity|`` instead of ```~astropy.units.Quantity```, and
+``|Particle|`` instead of
+```~plasmapy.particles.particle_class.Particle```. For an up-to-date
+list of substitutions, please refer to the `docs/common_links.rst`_
+file.
+
+Since substitutions are performed by Sphinx_ when the documentation is
+built, any substitution used in docstrings will not show up when using
+Python's `help` function (or the like). For example, when ``|Particle|``
+is used in a docstring, `help` will show it as ``|Particle|`` rather
+than ```~plasmapy.particles.particle_class.Particle```. Consequently,
+substitutions should not be used in docstrings when it is important that
+users have quick access to the full path of the `object` (such as in the
+``See Also`` section).
+
+Templating
+~~~~~~~~~~
+
+Sphinx_ uses the Jinja_ templating engine to generate HTML code. Jinja_
+may be used within the documentation when templating is necessary. For
+more details, please refer to `Sphinx's templating page`_.
+
+Writing documentation
+=====================
 
 Docstrings
-==========
+----------
+
+A docstring_ is a comment at the beginning of a function or another
+object that provides information on how to use that function (see
+:pep:`257`). Docstrings are designated by surrounding the content
+with triple quotes ``"""This is my docstring."""``.
+
+In order to improve readability and maintain consistency, PlasmaPy uses
+the numpydoc_ standard for docstrings. Docstring conventions for Python_
+are more generally described in :pep:`257`.
+
+.. tip::
 
-* All public classes, methods, and functions should have docstrings.
+   If a docstring contains math that utilizes LaTeX_ syntax, begin the
+   docstring with ``r"""`` instead of ``"""``.
 
-* PlasmaPy uses the `numpydoc`_ standard for docstrings.
+   In a normal string, backslashes are used to begin escape sequences,
+   and a single backslash needs to be represented with ``\\``. This
+   complication is avoided by beginning the docstring with ``r"""``,
+   which denotes the docstring as a `raw string`_. For example, the `raw
+   string`_ ``r""":math:`\alpha`"""`` will render the same as the normal
+   string ``""":math:`\\alpha`"""``.
 
-* Docstrings must be raw string `literals
-  <https://docs.python.org/3/reference/lexical_analysis.html#literals>`_
-  if they contain backslashes.  A raw string literal is denoted by
-  having an ``r`` immediately precede quotes or triple quotes:
+Example docstring
+~~~~~~~~~~~~~~~~~
+
+Here is an example docstring in the numpydoc_ format:
 
 .. code-block:: python
+   :caption: Example docstring
 
-   r"""
-   I did not like unstable eigenfunctions at first, but then they
-   grew on me.
-   """
+   import numpy as np
+   import warnings
 
-* Simple private functions may need only a one-line docstring.
+   def subtract(a, b, *, switch_order=False):
+       r"""
+       Compute the difference between two integers.
 
-Narrative Documentation
-=======================
+       Add ∼1–3 sentences here for an extended summary of what the
+       function does. This extended summary is a good place to briefly
+       define the quantity that is being returned.
 
-* Each subpackage must have narrative documentation describing its
-  use.
+       .. math::
 
-Substitutions
-=============
+          f(a, b) = a - b
+
+      Parameters
+      ----------
+      a : `float`
+          The left multiplicand.
+
+      b : `float`
+          The right multiplicand.
+
+      switch_order : `bool`, optional, keyword-only
+          If `True`, return :math:`a - b`. If `False`, then return
+          :math:`b - a`. Defaults to `True`.
+
+      Returns
+      -------
+      difference : float
+          The difference between ``a`` and ``b``.
+
+      Raises
+      ------
+      `ValueError`
+          If ``a`` or ``b`` is `~numpy.inf`.
+
+      Warns
+      -----
+      `UserWarning`
+          If ``a`` or ``b`` is `~numpy.nan`.
+
+      See Also
+      --------
+      add : Add two numbers.
+
+      Notes
+      -----
+      The "Notes" section provides extra information that cannot fit in
+      the extended summary near the beginning of the docstring. This
+      section should include a discussion of the physics behind a
+      particular concept that should be understandable to someone who is
+      taking their first plasma physics class. This section can include
+      a derivation of the quantity being calculated or a description of
+      a particular algorithm.
+
+      The next section contains example references to a journal article
+      [1]_ and a book [2]_.
+
+      References
+      ----------
+      .. [1] J. E. Foster, `Plasma-based water purification: Challenges and
+         prospects for the future <https://doi.org/10.1063/1.4977921>`_,
+         Physics of Plasmas, 22, 05501 (2017).
+
+      .. [2] E. Gamma, R. Helm, R. Johnson, J. Vlissides, `Design Patterns:
+         Elements of Reusable Object-Oriented Software
+         <https://www.oreilly.com/library/view/design-patterns-elements/0201633612/>`_
+
+      Examples
+      --------
+      Include a few example usages of the function here. Start with
+      simple examples and then increase complexity when necessary.
+
+      >>> from package.subpackage.module import subtract
+      >>> subtract(9, 6)
+      3
+
+      Here is an example of a multi-line function call.
+
+      >>> subtract(
+      ...     9, 6, switch_order=True,
+      ... )
+      -3
+
+      PlasmaPy's test suite will check that these commands provide the
+      output that follows each function call.
+      """
+      if np.isinf(a) or np.isinf(b):
+          raise ValueError("Cannot perform substraction operations involving infinity.")
+
+      warnings.warn("The subtract function encountered a nan value.", UserWarning)
+
+      return b - a if switch_order else a - b
+
+Template docstring
+~~~~~~~~~~~~~~~~~~
+
+This template docstring may be copied into new functions. Usually only
+some of the sections will be necessary for a particular function, and
+unnecessary sections should be deleted. Any sections that are included
+should be in the order provided.
+
+.. code-block:: python
+  :caption: Docstring template
+
+  def sample_function():
+      r"""
+      Compute ...
+
+      Parameters
+      ----------
+
+      Returns
+      -------
+
+      Raises
+      ------
+
+      Warns
+      -----
+
+      See Also
+      --------
+
+      Notes
+      -----
+
+      References
+      ----------
+
+      Examples
+      --------
+
+      """
+
+Documentation guidelines
+========================
+
+This section contains guidelines and best practices for writing
+documentation for PlasmaPy and affiliated packages.
+
+* Write documentation to be understandable to students taking their
+  first course or beginning their first research project in plasma
+  science. Include highly technical information only when necessary.
+
+* Use technical jargon sparingly. Define technical jargon when
+  necessary.
+
+* Use the `active voice`_ in the present tense.
+
+* Keep the documentation style consistent within a file or module, and
+  preferably across all of `PlasmaPy's documentation`_.
+
+* Update code and corresponding documentation at the same time.
+
+* Write sentences that are simple, concise, and direct rather than
+  complicated, vague, or ambiguous. Prefer sentences with ≲ 20 words.
+
+* Avoid idioms, metaphors, and references that are specific to a
+  particular culture.
+
+* Many words and software packages have more than one common spelling or
+  acronym. Use the spelling that is used in the file you are modifying,
+  which is preferably the spelling used throughout `PlasmaPy's
+  documentation`_.
+
+  * More generally, it is preferable to use the spelling that is used in
+    `Python's documentation`_ or the spelling that is used most
+    commonly.
+
+  * Represent names and acronyms for a software package or language as
+    they are represented in the documentation for each project. Common
+    examples include "Python", "Astropy", "NumPy", and "reST".
+
+* When referencing PlasmaPy functionality, write the full namespace path
+  to where the functionality is defined, not where it is conveniently
+  accessed. For example, write
+  ```~plasmapy.formulary.parameters.Alfven_speed``` rather than
+  ```~plasmapy.formulary.Alfven_speed```.
+
+  This does not necessarily need to be done when referencing external
+  packages, since each package may have their own standard. For example,
+  Astropy's |Quantity| class is defined in
+  ```astropy.units.quantity.Quantity``` but is also indexed at
+  ```~astropy.units.Quantity``` so either option will link to the same
+  documentation.
+
+* For readability, limit documentation line lengths to ≲ 72 characters
+  (excluding leading spaces in docstrings). Longer line lengths may be
+  used when necessary (e.g., for hyperlinks).
+
+  .. note::
+
+     Studies typically show that line lengths of 50–75 characters are
+     optimal for readability.
+
+* Use indentations of 3 spaces for reST_ blocks.
+
+* Store images within the `docs/_static`_ directory, except for images
+  that are generated during the Sphinx_ build. The `docs/_static`_
+  directory contains files that are used for the online documentation
+  but are not generated during the Sphinx_ build.
+
+* Avoid linking to websites that might disappear due to `link rot`_ such
+  as documents hosted on personal websites.
+
+  * When including references, use a link that includes a `persistent
+    identifier`_ such as a digital object identifier (DOI) when one is
+    available (e.g., `https://doi.org/10.5281/zenodo.4602818`_).
+
+  * Wikipedia_ articles may be linked to when they contain a
+    well-developed and accurate description of a concept.
+
+* Include both the original references for a topic as well as accessible
+  pedagogical references. Prefer references that are open access over
+  references that require purchase of a subscription or are behind a
+  paywall_.
+
+.. note::
+
+   Emphasize important points with admonitions_ like this one.
+
+* Start the names of all physical units with a lower case letter, except
+  at the beginning of a sentence and for "degree Celsius".
+
+* Physical unit symbols should not be formatted as math. If units are
+  needed inside a math block, use LaTeX_'s ``\mbox`` command as in the
+  example below. A tilde will need to precede the unit so that
+
+  .. code-block:: rst
+
+     The speed of light is approximately :math:`3 × 10^8` m/s or
+
+     .. math::
+
+        3 × 10^{10} \mbox{~cm/s}
+
+  This reST_ block renders as:
+
+     The speed of light is approximately :math:`3 × 10^8` m/s or
+
+     .. math::
+
+        3 × 10^{10} \mbox{cm/s}
+
+* The names of chemical elements are lower case, except at the beginning
+  of a sentence.
+
+* Particle and chemical symbols should be formatted as regular text.
+  The ``:sub:`` and ``:sup:`` roles should be used for subscripts and
+  superscripts, respectively.
+
+  Because interpreted text must normally be surrounded by whitespace or
+  punctuation, use a backslash followed by a space for the interpreted
+  text to show up immediately next to the regular text. This is not
+  necessary before a period or comma.
+
+  .. code-block:: rst
+
+     The symbol for helium is He.
+
+     The symbol for an electron is e\ :sup:`-`.
+
+     An alpha particle may be represented as :sup:`4`\ He\ :sup:`1+`.
+
+  This reST_ block renders as:
+
+     The symbol for helium is He.
+
+     The symbol for an electron is e\ :sup:`-`.
+
+     An alpha particle may be represented as :sup:`4`\ He\ :sup:`1+`.
+
+Docstring guidelines
+--------------------
+
+* All functions, classes, and objects that are part of the public
+  Application Programming Interface (API) must have a docstring that
+  follows the numpydoc_ standard. Refer to the numpydoc_ standard for
+  how to write docstrings for classes, class attributes, and constants.
+
+* The short summary statement at the beginning of a docstring should be
+  one line long, but may be longer if necessary.
+
+* The extended summary that immediately follows the short summary should
+  be ≲ 4 sentences long. Any additional information should included in
+  the "Notes" section.
+
+* The short summary should start on the line immediately following the
+  triple quotes. There should not be any blank lines immediately before
+  the closing triple quotes.
+
+* The first line of the docstring for a function or method should begin
+  with a word like "Calculate" or "Compute" and end with a period.
+
+* The first line of an object that is not callable (for example, an
+  attribute of a class decorated with `property`) should not begin with
+  a verb and should end with a period.
+
+* Keep the docstring indented at the same level as the ``r"""`` or
+  ``"""`` that begins the docstring, except for reST_ constructs like
+  lists, math, and code blocks. Use an indentation of four spaces more
+  than the declaration of the object.
+
+  .. code-block:: python
+
+     def f():
+         """This is indented four spaces relative to the `def` statement."""
+
+* The first sentence of a docstring of a function should include a
+  concise definition of the quantity being calculated, as in the
+  following example.
+
+  .. code-block:: python
+
+     def beta(T, n, B):
+         """Compute the ratio of thermal pressure to magnetic pressure."""
+
+  When the definition of the quantity being calculated is unable to fit
+  on ∼1–2 lines, include the definition in the extended summary instead.
+
+  .. code-block:: python
+
+     def beta(T, n, B):
+         """
+         Compute plasma beta.
+
+         Plasma beta is the ratio of thermal pressure to magnetic pressure.
+         """
+
+* Put any necessary highly technical information in the "Notes" section
+  of a docstring.
+
+* Private code objects (e.g., code objects that begin with a single
+  underscore, like ``_private_object``) should have docstrings. A
+  docstring for a private code object may be a single line, and
+  otherwise should be in numpydoc_ format.
+
+  * Docstrings for private code objects do not get rendered in the
+    online documentation, and should be intended for contributors.
+
+* Dunder methods (e.g., code objects like ``__add__`` that begin and end
+  with two underscores) only need docstrings if it is necessary to
+  describe non-standard or potentially unexpected behavior. Custom
+  behavior associated with dunder methods should be described in the
+  class-level documentation.
+
+  * Docstrings for most dunder methods are not rendered in the online
+    documentation and should therefore be intended for contributors.
+
+  * Docstrings for ``__init__``, ``__new__``, and ``__call__`` are
+    rendered in the documentation, and should be written for users. The
+    docstrings for ``__init__`` and ``__new__`` are included in the
+    class-level docstring, while the docstring for ``__call__`` is
+    included in the methods summary of a class.
+
+* When an attribute in a class has both a getter (which is the method
+  decorated with `property`) and a ``setter`` decoration, then the
+  getter and ``setter`` functionality should be documented in the
+  docstring of the attribute decorated with ``@property``.
+
+  .. code-block:: python
+
+     class Person:
+         @property
+         def age(self):
+             """Document both getter and setter here."""
+             return self._age
+
+         @age.setter
+         def age(self, n):
+             self._age = n
+
+Narrative documentation guidelines
+----------------------------------
+
+* Each top-level subpackage must have corresponding narrative
+  documentation.
+
+* Use narrative documentation to describe how different functionality
+  works together.
+
+* Narrative documentation should be used when the full scope of some
+  functionality cannot be adequately described within only the
+  docstrings of that functionality.
+
+* Use title case for page titles (e.g., "This is Title Case") and
+  sentence case for all other headings (e.g., "This is sentence case").
+
+* When the narrative documentation does not index a subpackage (a
+  directory) or module (a :file:`.py` file) with ``automodule``,
+  ``automodapi``, or the like, then it is required to create a stub file
+  for that particular subpackage or module in `docs/api_static`_ . For
+  example, the stub file for `plasmapy.particles.atomic` is placed at
+  :file:`docs/api_static/plasampy.particles.atomic.rst` and its contents
+  look like:
+
+  .. code-block:: rst
+
+     :orphan:
 
-The `common_links.rst
-<https://github.com/PlasmaPy/PlasmaPy/blob/master/docs/common_links.rst>`_
-file defines reStructuredText substitutions that can be used in
-PlasmaPy's documentation.
+     `plasmapy.particles.atomic`
+     ===========================
 
-.. code-block:: RST
+     .. currentmodule:: plasmapy.particles.atomic
 
-    Instead of writing `~plasmapy.particles.particle_class.Particle`,
-    we can write |Particle|.
+     .. automodapi::  plasmapy.particles.atomic
 
-Substitutions should be defined when they are used in multiple files.
+.. _`active voice`: https://en.wikipedia.org/wiki/Active_voice
+.. _admonitions: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
+.. _`configuration options`: https://www.sphinx-doc.org/en/master/usage/configuration.html
+.. _CSS: https://en.wikipedia.org/wiki/CSS
+.. _`define substitutions`: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
+.. _`docs/_static`: https://github.com/PlasmaPy/PlasmaPy/blob/main/docs/_static/
+.. _`docs/_static/sphinx_rtd_overrides.css`: https://github.com/PlasmaPy/PlasmaPy/blob/main/docs/_static/rtd_theme_overrides.css
+.. _`docs/api_static`: https://github.com/PlasmaPy/PlasmaPy/blob/main/docs/api_static/
+.. _`docs/conf.py`: https://github.com/PlasmaPy/PlasmaPy/blob/main/docs/conf.py
+.. _docstring: https://en.wikipedia.org/wiki/Docstring
+.. _`GitHub Flavored Markdown`: https://github.github.com/gfm/
+.. _Graphviz: https://graphviz.org/
+.. _`https://docs.plasmapy.org/`: https://docs.plasmapy.org/
+.. _`https://docs.plasmapy.org/en/stable/`: https://docs.plasmapy.org/en/stable/
+.. _`https://docs.plasmapy.org/en/latest/`: https://docs.plasmapy.org/en/latest/
+.. _`https://doi.org/10.5281/zenodo.4602818`: https://doi.org/10.5281/zenodo.4602818
+.. _`IPython.sphinxext.ipython_console_highlighting`: https://ipython.readthedocs.io/en/stable/sphinxext.html?highlight=IPython.sphinxext.ipython_console_highlighting#ipython-sphinx-directive-module
+.. _Jinja: https://jinja.palletsprojects.com/
+.. _LaTeX: https://www.latex-project.org/
+.. _`link rot`: https://en.wikipedia.org/wiki/Link_rot
+.. _make: https://www.gnu.org/software/make/
+.. _MathJax: https://www.mathjax.org/
+.. _nbsphinx: https://nbsphinx.readthedocs.io
+.. _pandas: https://pandas.pydata.org/
+.. _paywall: https://en.wikipedia.org/wiki/Paywall
+.. _`persistent identifier`: https://en.wikipedia.org/wiki/Persistent_identifier
+.. _`raise an issue`: https://github.com/PlasmaPy/PlasmaPy/issues/new?title=Improve+documentation+for...&labels=Documentation
+.. _`raw string`: https://docs.python.org/3/reference/lexical_analysis.html#literals
+.. _`Read the Docs Sphinx Theme`: https://sphinx-rtd-theme.readthedocs.io/
+.. _`reStructuredText (reST)`: https://docutils.sourceforge.io/rst.html
+.. _sphinx_automodapi: https://sphinx-automodapi.readthedocs.io/
+.. _`sphinx-build`: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+.. _`sphinx_changelog`: https://sphinx-changelog.readthedocs.io
+.. _`sphinx_copybutton`: https://sphinx-copybutton.readthedocs.io
+.. _`sphinx_gallery.load_style`: https://sphinx-gallery.github.io/stable/advanced.html?highlight=load_style#using-only-sphinx-gallery-styles
+.. _`Sphinx's templating page`: https://www.sphinx-doc.org/en/master/templating.html
+.. _`style overrides`: https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html
+.. _Wikipedia: https://www.wikipedia.org/
diff --git a/docs/development/install_dev.rst b/docs/development/install_dev.rst
index 5cc01ce5..84132571 100644
--- a/docs/development/install_dev.rst
+++ b/docs/development/install_dev.rst
@@ -7,9 +7,8 @@ Installing PlasmaPy for Development
 Obtaining PlasmaPy source code
 ==============================
 
-After creating your GitHub account, go to the `PlasmaPy repository on
-GitHub <https://github.com/PlasmaPy/plasmapy>`_ and **fork a copy of
-PlasmaPy to your account**.
+After creating your GitHub account, go to `PlasmaPy's GitHub repository`_
+and **fork a copy of PlasmaPy to your account**.
 
 To access Git commands on Windows, try `Git Bash
 <https://git-scm.com/downloads>`_.
diff --git a/docs/install.rst b/docs/install.rst
index cfa0ac2e..ede5261e 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -149,7 +149,6 @@ by running
 Note, however, that this does not download all the dependencies. Check the
 `requirements/requirements.txt` file for the current set.
 
-.. _PlasmaPy's GitHub repository: https://github.com/PlasmaPy/PlasmaPy
 .. _from PyPI: https://pypi.org/project/plasmapy/
 .. _from Zenodo: https://doi.org/10.5281/zenodo.1436011
 .. _clone a repository using SSH: https://help.github.com/en/github/using-git/which-remote-url-should-i-use#cloning-with-ssh-urls
diff --git a/docs/plasmapy_sphinx/__init__.py b/docs/plasmapy_sphinx/__init__.py
index c9f74054..3f105d1b 100644
--- a/docs/plasmapy_sphinx/__init__.py
+++ b/docs/plasmapy_sphinx/__init__.py
@@ -1,6 +1,6 @@
 """
-This `Sphinx <https://www.sphinx-doc.org/en/master/>`_ extension package contains
-custom documentation functionality used to document
+This `Sphinx <https://www.sphinx-doc.org/en/master/>`__ extension package
+contains custom documentation functionality used to document
 `PlasmaPy's packages <https://github.com/PlasmaPy>`_ .
 
 .. contents:: Content
diff --git a/docs/whatsnew/0.1.0.rst b/docs/whatsnew/0.1.0.rst
index a1c4aa6a..f35a4841 100644
--- a/docs/whatsnew/0.1.0.rst
+++ b/docs/whatsnew/0.1.0.rst
@@ -34,8 +34,7 @@ New Features
   <http://docs.plasmapy.org>`_ that is hosted by `Read the Docs
   <https://readthedocs.org/>`_.
 
-  - Automated documentation builds with `Sphinx
-    <http://www.sphinx-doc.org/>`_.
+  - Automated documentation builds with Sphinx_.
 
   - Wrote narrative documentation for each subpackage.
 
diff --git a/docs/whatsnew/0.3.0.rst b/docs/whatsnew/0.3.0.rst
index 6eec3b49..889492e1 100644
--- a/docs/whatsnew/0.3.0.rst
+++ b/docs/whatsnew/0.3.0.rst
@@ -52,7 +52,7 @@ Trivial/Internal Changes
   :func:`plasmapy.formulary.quantum._chemical_potential_interp`, add a `RaiseNotImplementedError` due
   to bug outlined in issue `<https://github.com/PlasmaPy/PlasmaPy/issues/726>`_.  Associated pytests
   are marked with `pytest.mark.xfails` and doctests are marked with `doctests: +SKIP`. (`#722 <https://github.com/plasmapy/plasmapy/pull/722>`__)
-- Add `Towncrier <https://github.com/hawkowl/towncrier>`_ automated changelog creation support (`#643 <https://github.com/plasmapy/plasmapy/pull/643>`__)
+- Add `towncrier`_ automated changelog creation support (`#643 <https://github.com/plasmapy/plasmapy/pull/643>`__)
 - Move existing "check" decorators to new ``plasmapy.utils.decorators`` module (`#647 <https://github.com/plasmapy/plasmapy/pull/647>`__)
 - Allow running our sphinx-gallery examples as Jupyter notebooks via Binder (`#656 <https://github.com/plasmapy/plasmapy/pull/656>`__)
 - Overhaul CI setup, following the example of SunPy (`#657 <https://github.com/plasmapy/plasmapy/pull/657>`__)
diff --git a/docs/whatsnew/0.4.0.rst b/docs/whatsnew/0.4.0.rst
index 9a5c3c4b..aa0fa981 100644
--- a/docs/whatsnew/0.4.0.rst
+++ b/docs/whatsnew/0.4.0.rst
@@ -105,7 +105,7 @@ Improved Documentation
 - Reorder documentation page (`#777 <https://github.com/plasmapy/plasmapy/pull/777>`__)
 - Fix failing documentation build due to duplicate docstrings for
   `ParticleTracker.kinetic_energy_history` and incompatibility of `sphinx-automodapi`
-  with `sphinx` `v3.0.0`. (`#780 <https://github.com/plasmapy/plasmapy/pull/780>`__)
+  with Sphinx_ `v3.0.0`. (`#780 <https://github.com/plasmapy/plasmapy/pull/780>`__)
 - Automate definition of documentation `release` and `version` in `docs/conf.py` with
   `plasmapy.__version__`. (`#781 <https://github.com/plasmapy/plasmapy/pull/781>`__)
 - Add a docstring to ``__init__.py`` in `plasmapy.formulary`. (`#788 <https://github.com/plasmapy/plasmapy/pull/788>`__)
diff --git a/plasmapy/formulary/parameters.py b/plasmapy/formulary/parameters.py
index 60f2f7ea..9ced1126 100644
--- a/plasmapy/formulary/parameters.py
+++ b/plasmapy/formulary/parameters.py
@@ -60,7 +60,7 @@
     check_relativistic,
     validate_quantities,
 )
-from plasmapy.utils.exceptions import PhysicsWarning
+from plasmapy.utils.exceptions import PhysicsWarning, PlasmaPyFutureWarning
 
 __all__ += __aliases__
 
@@ -1094,6 +1094,7 @@ def gyrofrequency(B: u.T, particle: Particle, signed=False, Z=None) -> u.rad / u
 @validate_quantities(
     Vperp={"can_be_nan": True},
     T_i={"can_be_nan": True, "equivalencies": u.temperature_energy()},
+    T={"can_be_nan": True, "equivalencies": u.temperature_energy()},
     validations_on_return={"equivalencies": u.dimensionless_angles()},
 )
 def gyroradius(
@@ -1102,6 +1103,7 @@ def gyroradius(
     *,
     Vperp: u.m / u.s = np.nan * u.m / u.s,
     T_i: u.K = np.nan * u.K,
+    T: u.K = np.nan * u.K,
 ) -> u.m:
     r"""Return the particle gyroradius.
 
@@ -1122,8 +1124,12 @@ def gyroradius(
         The component of particle velocity that is perpendicular to the
         magnetic field in units convertible to meters per second.
 
+    T : `~astropy.units.Quantity`, optional, keyword-only
+        The particle temperature in units convertible to kelvin.
+
     T_i : `~astropy.units.Quantity`, optional, keyword-only
         The particle temperature in units convertible to kelvin.
+        Note: Deprecated. Use T instead.
 
     Returns
     -------
@@ -1152,9 +1158,9 @@ def gyroradius(
 
     Notes
     -----
-    One but not both of ``Vperp`` and ``T_i`` must be inputted.
+    One but not both of ``Vperp`` and ``T`` must be inputted.
 
-    If any of ``B``, ``Vperp``, or ``T_i`` is a number rather than a
+    If any of ``B``, ``Vperp``, or ``T`` is a number rather than a
     `~astropy.units.Quantity`, then SI units will be assumed and a
     warning will be raised.
 
@@ -1173,69 +1179,78 @@ def gyroradius(
     Examples
     --------
     >>> from astropy import units as u
-    >>> gyroradius(0.2*u.T, particle='p+', T_i=1e5*u.K)
+    >>> gyroradius(0.2*u.T, particle='p+', T=1e5*u.K)
     <Quantity 0.002120... m>
-    >>> gyroradius(0.2*u.T, particle='p+', T_i=1e5*u.K)
+    >>> gyroradius(0.2*u.T, particle='p+', T=1e5*u.K)
     <Quantity 0.002120... m>
-    >>> gyroradius(5*u.uG, particle='alpha', T_i=1*u.eV)
+    >>> gyroradius(5*u.uG, particle='alpha', T=1*u.eV)
     <Quantity 288002.38... m>
     >>> gyroradius(400*u.G, particle='Fe+++', Vperp=1e7*u.m/u.s)
     <Quantity 48.23129... m>
-    >>> gyroradius(B=0.01*u.T, particle='e-', T_i=1e6*u.K)
+    >>> gyroradius(B=0.01*u.T, particle='e-', T=1e6*u.K)
     <Quantity 0.003130... m>
     >>> gyroradius(0.01*u.T, 'e-', Vperp=1e6*u.m/u.s)
     <Quantity 0.000568... m>
-    >>> gyroradius(0.2*u.T, 'e-', T_i=1e5*u.K)
+    >>> gyroradius(0.2*u.T, 'e-', T=1e5*u.K)
     <Quantity 4.94949...e-05 m>
-    >>> gyroradius(5*u.uG, 'e-', T_i=1*u.eV)
+    >>> gyroradius(5*u.uG, 'e-', T=1*u.eV)
     <Quantity 6744.25... m>
     >>> gyroradius(400*u.G, 'e-', Vperp=1e7*u.m/u.s)
     <Quantity 0.001421... m>
     """
 
-    isfinite_Ti = np.isfinite(T_i)
+    # Backwards Compatibility and Deprecation check for keyword T_i
+    if not np.isnan(T_i):
+        warnings.warn(
+            "Keyword T_i is deprecated, use T instead.",
+            PlasmaPyFutureWarning,
+        )
+        if np.isnan(T):
+            T = T_i
+
+    isfinite_T = np.isfinite(T)
     isfinite_Vperp = np.isfinite(Vperp)
 
-    # check 1: ensure either Vperp or T_i invalid, keeping in mind that
+    # check 1: ensure either Vperp or T invalid, keeping in mind that
     # the underlying values of the astropy quantity may be numpy arrays
-    if np.any(np.logical_and(isfinite_Vperp, isfinite_Ti)):
+    if np.any(np.logical_and(isfinite_Vperp, isfinite_T)):
         raise ValueError(
-            "Must give Vperp or T_i, but not both, as arguments to gyroradius"
+            "Must give Vperp or T, but not both, as arguments to gyroradius"
         )
 
     # check 2: get Vperp as the thermal speed if is not already a valid input
     if np.isscalar(Vperp.value) and np.isscalar(
-        T_i.value
-    ):  # both T_i and Vperp are scalars
+        T.value
+    ):  # both T and Vperp are scalars
         # we know exactly one of them is nan from check 1
-        if isfinite_Ti:
-            # T_i is valid, so use it to determine Vperp
-            Vperp = thermal_speed(T_i, particle=particle)
+        if isfinite_T:
+            # T is valid, so use it to determine Vperp
+            Vperp = thermal_speed(T, particle=particle)
         # else: Vperp is already valid, do nothing
-    elif np.isscalar(Vperp.value):  # only T_i is an array
-        # this means either Vperp must be nan, or T_i must be array of all nan,
+    elif np.isscalar(Vperp.value):  # only T is an array
+        # this means either Vperp must be nan, or T must be array of all nan,
         # or else we couldn't have gotten through check 1
         if isfinite_Vperp:
-            # Vperp is valid, T_i is a vector that is all nan
+            # Vperp is valid, T is a vector that is all nan
             # uh...
-            Vperp = np.repeat(Vperp, len(T_i))
+            Vperp = np.repeat(Vperp, len(T))
         else:
-            # normal case where Vperp is scalar nan and T_i is valid array
-            Vperp = thermal_speed(T_i, particle=particle)
-    elif np.isscalar(T_i.value):  # only Vperp is an array
-        # this means either T_i must be nan, or V_perp must be array of all nan,
+            # normal case where Vperp is scalar nan and T is valid array
+            Vperp = thermal_speed(T, particle=particle)
+    elif np.isscalar(T.value):  # only Vperp is an array
+        # this means either T must be nan, or V_perp must be array of all nan,
         # or else we couldn't have gotten through check 1
-        if isfinite_Ti:
-            # T_i is valid, V_perp is an array of all nan
+        if isfinite_T:
+            # T is valid, V_perp is an array of all nan
             # uh...
-            Vperp = thermal_speed(np.repeat(T_i, len(Vperp)), particle=particle)
-        # else: normal case where T_i is scalar nan and Vperp is already a valid array
+            Vperp = thermal_speed(np.repeat(T, len(Vperp)), particle=particle)
+        # else: normal case where T is scalar nan and Vperp is already a valid array
         # so, do nothing
-    else:  # both T_i and Vperp are arrays
+    else:  # both T and Vperp are arrays
         # we know all the elementwise combinations have one nan and one finite, due to check 1
-        # use the valid Vperps, and replace the others with those calculated from T_i
+        # use the valid Vperps, and replace the others with those calculated from T
         Vperp = Vperp.copy()  # avoid changing Vperp's value outside function
-        Vperp[isfinite_Ti] = thermal_speed(T_i[isfinite_Ti], particle=particle)
+        Vperp[isfinite_T] = thermal_speed(T[isfinite_T], particle=particle)
 
     omega_ci = gyrofrequency(B, particle)
 
diff --git a/requirements/docs.txt b/requirements/docs.txt
index 4f2c2b0d..bb2488f6 100644
--- a/requirements/docs.txt
+++ b/requirements/docs.txt
@@ -1,7 +1,7 @@
 # these are dependencies required to build package documentation
 # ought to mirror 'docs' under options.extras_require in setup.cfg
 -r extras.txt
-docutils < 0.18
+docutils != 0.17
 ipykernel
 ipywidgets
 nbsphinx
diff --git a/setup.cfg b/setup.cfg
index 8914d30c..33c3e02c 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -76,7 +76,7 @@ tests =
 docs =
   # ought to mirror requirements/docs.txt
   %(extras)s
-  docutils < 0.18
+  docutils != 0.17
   ipykernel
   ipywidgets
   nbsphinx


Test patch:
diff --git a/docs/development/testing_guide.rst b/docs/development/testing_guide.rst
index 62642fae..e8983a2a 100644
--- a/docs/development/testing_guide.rst
+++ b/docs/development/testing_guide.rst
@@ -59,8 +59,7 @@ Running tests on GitHub
 The recommended way to run PlasmaPy's full test suite when contributing
 code is to `create a pull request
 <https://help.github.com/articles/creating-a-pull-request/>`_ from your
-development branch to `PlasmaPy's GitHub repository
-<https://github.com/PlasmaPy/PlasmaPy>`_.  The test suite will be run
+development branch to `PlasmaPy's GitHub repository`_.  The test suite will be run
 when the pull request is created and every time your development branch
 is subsequently updated.
 
diff --git a/plasmapy/formulary/tests/test_parameters.py b/plasmapy/formulary/tests/test_parameters.py
index fcbb60d4..14d5e207 100644
--- a/plasmapy/formulary/tests/test_parameters.py
+++ b/plasmapy/formulary/tests/test_parameters.py
@@ -52,6 +52,7 @@
 from plasmapy.utils.exceptions import (
     PhysicsError,
     PhysicsWarning,
+    PlasmaPyFutureWarning,
     RelativityError,
     RelativityWarning,
 )
@@ -798,13 +799,13 @@ def test_gyrofrequency():
 def test_gyroradius():
     r"""Test the gyroradius function in parameters.py."""
 
-    assert gyroradius(B, "e-", T_i=T_e).unit.is_equivalent(u.m)
+    assert gyroradius(B, "e-", T=T_e).unit.is_equivalent(u.m)
 
     assert gyroradius(B, "e-", Vperp=25 * u.m / u.s).unit.is_equivalent(u.m)
 
     # test for possiblity to allow nan for input values
-    assert np.isnan(gyroradius(np.nan * u.T, particle="e-", T_i=1 * u.K))
-    assert np.isnan(gyroradius(1 * u.T, particle="e-", T_i=np.nan * u.K))
+    assert np.isnan(gyroradius(np.nan * u.T, particle="e-", T=1 * u.K))
+    assert np.isnan(gyroradius(1 * u.T, particle="e-", T=np.nan * u.K))
     assert np.isnan(gyroradius(1 * u.T, particle="e-", Vperp=np.nan * u.m / u.s))
 
     Vperp = 1e6 * u.m / u.s
@@ -830,7 +831,7 @@ def test_gyroradius():
     assert np.isnan(gyroradius(np.nan * u.T, "e-", Vperp=1 * u.m / u.s))
 
     with pytest.raises(ValueError):
-        gyroradius(3.14159 * u.T, "e-", T_i=-1 * u.K)
+        gyroradius(3.14159 * u.T, "e-", T=-1 * u.K)
 
     with pytest.warns(u.UnitsWarning):
         assert gyroradius(1.0, "e-", Vperp=1.0) == gyroradius(
@@ -838,24 +839,26 @@ def test_gyroradius():
         )
 
     with pytest.warns(u.UnitsWarning):
-        assert gyroradius(1.1, "e-", T_i=1.2) == gyroradius(
-            1.1 * u.T, "e-", T_i=1.2 * u.K
-        )
+        assert gyroradius(1.1, "e-", T=1.2) == gyroradius(1.1 * u.T, "e-", T=1.2 * u.K)
 
     with pytest.raises(ValueError):
-        gyroradius(1.1 * u.T, "e-", Vperp=1 * u.m / u.s, T_i=1.2 * u.K)
+        gyroradius(1.1 * u.T, "e-", Vperp=1 * u.m / u.s, T=1.2 * u.K)
 
     with pytest.raises(u.UnitTypeError):
-        gyroradius(1.1 * u.T, "e-", Vperp=1.1 * u.m, T_i=1.2 * u.K)
+        gyroradius(1.1 * u.T, "e-", Vperp=1.1 * u.m, T=1.2 * u.K)
+
+    # Check for Deprecation warning when using T_i instead of T
+    with pytest.warns(PlasmaPyFutureWarning):
+        gyroradius(1.1 * u.T, "e-", T_i=1.2 * u.K)
 
-    assert gyroradius(B, particle="p", T_i=T_i).unit.is_equivalent(u.m)
+    assert gyroradius(B, particle="p", T=T_i).unit.is_equivalent(u.m)
 
     assert gyroradius(B, particle="p", Vperp=25 * u.m / u.s).unit.is_equivalent(u.m)
 
     # Case when Z=1 is assumed
     assert np.isclose(
-        gyroradius(B, particle="p", T_i=T_i),
-        gyroradius(B, particle="H+", T_i=T_i),
+        gyroradius(B, particle="p", T=T_i),
+        gyroradius(B, particle="H+", T=T_i),
         atol=1e-6 * u.m,
     )
 
@@ -876,16 +879,16 @@ def test_gyroradius():
     particle2 = "alpha"
     Vperp2 = thermal_speed(T2, particle=particle2)
     gyro_by_vperp = gyroradius(B2, particle="alpha", Vperp=Vperp2)
-    assert gyro_by_vperp == gyroradius(B2, particle="alpha", T_i=T2)
+    assert gyro_by_vperp == gyroradius(B2, particle="alpha", T=T2)
 
-    explicit_positron_gyro = gyroradius(1 * u.T, particle="positron", T_i=1 * u.MK)
-    assert explicit_positron_gyro == gyroradius(1 * u.T, "e-", T_i=1 * u.MK)
+    explicit_positron_gyro = gyroradius(1 * u.T, particle="positron", T=1 * u.MK)
+    assert explicit_positron_gyro == gyroradius(1 * u.T, "e-", T=1 * u.MK)
 
     with pytest.raises(TypeError):
         gyroradius(u.T, particle="p", Vperp=8 * u.m / u.s)
 
     with pytest.raises(ValueError):
-        gyroradius(B, particle="p", T_i=-1 * u.K)
+        gyroradius(B, particle="p", T=-1 * u.K)
 
     with pytest.warns(u.UnitsWarning):
         gyro_without_units = gyroradius(1.0, particle="p", Vperp=1.0)
@@ -893,65 +896,65 @@ def test_gyroradius():
         assert gyro_without_units == gyro_with_units
 
     with pytest.warns(u.UnitsWarning):
-        gyro_t_without_units = gyroradius(1.1, particle="p", T_i=1.2)
-        gyro_t_with_units = gyroradius(1.1 * u.T, particle="p", T_i=1.2 * u.K)
+        gyro_t_without_units = gyroradius(1.1, particle="p", T=1.2)
+        gyro_t_with_units = gyroradius(1.1 * u.T, particle="p", T=1.2 * u.K)
         assert gyro_t_with_units == gyro_t_without_units
 
     with pytest.raises(ValueError):
-        gyroradius(1.1 * u.T, particle="p", Vperp=1 * u.m / u.s, T_i=1.2 * u.K)
+        gyroradius(1.1 * u.T, particle="p", Vperp=1 * u.m / u.s, T=1.2 * u.K)
 
     with pytest.raises(u.UnitTypeError):
-        gyroradius(1.1 * u.T, particle="p", Vperp=1.1 * u.m, T_i=1.2 * u.K)
+        gyroradius(1.1 * u.T, particle="p", Vperp=1.1 * u.m, T=1.2 * u.K)
 
     with pytest.raises(u.UnitTypeError):
-        gyroradius(1.1 * u.T, particle="p", Vperp=1.2 * u.m, T_i=1.1 * u.K)
+        gyroradius(1.1 * u.T, particle="p", Vperp=1.2 * u.m, T=1.1 * u.K)
 
 
 class Test_gyroradius:
 
-    # some custom numpy array tests here, because of the T_i / Vperp situation
+    # some custom numpy array tests here, because of the T / Vperp situation
     def test_handle_numpy_array(self):
         # Tests to verify that can handle Quantities with numpy array as the value:
         assert gyroradius(B_arr, "e-", Vperp=V_arr)[0] == gyroradius(
             B_arr[0], "e-", Vperp=V_arr[0]
         )
-        assert gyroradius(B_arr, "e-", T_i=T_arr)[0] == gyroradius(
-            B_arr[0], "e-", T_i=T_arr[0]
+        assert gyroradius(B_arr, "e-", T=T_arr)[0] == gyroradius(
+            B_arr[0], "e-", T=T_arr[0]
         )
 
     def test_handle_mixed_Qarrays(self):
-        # If both Vperp or Ti are input as Qarrays, but only one of the two is valid
+        # If both Vperp or T are input as Qarrays, but only one of the two is valid
         # at each element, then that's fine, the function should work:
-        assert gyroradius(B_arr, "e-", Vperp=V_nanarr, T_i=T_nanarr2)[0] == gyroradius(
-            B_arr[0], "e-", Vperp=V_nanarr[0], T_i=T_nanarr2[0]
+        assert gyroradius(B_arr, "e-", Vperp=V_nanarr, T=T_nanarr2)[0] == gyroradius(
+            B_arr[0], "e-", Vperp=V_nanarr[0], T=T_nanarr2[0]
         )
 
     def test_raise_two_valid_inputs(self):
-        # If both Vperp or Ti are nan-less, Qarrays or not, should raise ValueError:
+        # If both Vperp or T are nan-less, Qarrays or not, should raise ValueError:
         with pytest.raises(ValueError):
-            gyroradius(B_arr, "e-", Vperp=V, T_i=T_arr)
+            gyroradius(B_arr, "e-", Vperp=V, T=T_arr)
         with pytest.raises(ValueError):
-            gyroradius(B_arr, "e-", Vperp=V_arr, T_i=T_i)
+            gyroradius(B_arr, "e-", Vperp=V_arr, T=T_i)
 
     def test_all_valid_and_one_valid(self):
-        # If one of (Vperp, Ti) is a valid and one is Qarray with at least one valid, ValueError:
+        # If one of (Vperp, T) is a valid and one is Qarray with at least one valid, ValueError:
         with pytest.raises(ValueError):
-            gyroradius(B_arr, "e-", Vperp=V, T_i=T_nanarr)
+            gyroradius(B_arr, "e-", Vperp=V, T=T_nanarr)
         with pytest.raises(ValueError):
-            gyroradius(B_arr, "e-", Vperp=V_nanarr, T_i=T_i)
+            gyroradius(B_arr, "e-", Vperp=V_nanarr, T=T_i)
 
     def test_scalar_and_nan_qarray(self):
-        # If either Vperp or Ti is a valid scalar and the other is a Qarray of all nans,
+        # If either Vperp or T is a valid scalar and the other is a Qarray of all nans,
         # should do something valid and not raise a ValueError
-        assert np.all(np.isfinite(gyroradius(B_arr, "e-", Vperp=V, T_i=T_allnanarr)))
-        assert np.all(np.isfinite(gyroradius(B_arr, "e-", Vperp=V_allnanarr, T_i=T_i)))
+        assert np.all(np.isfinite(gyroradius(B_arr, "e-", Vperp=V, T=T_allnanarr)))
+        assert np.all(np.isfinite(gyroradius(B_arr, "e-", Vperp=V_allnanarr, T=T_i)))
 
     def test_keeps_arguments_unchanged(self):
         Vperp1 = u.Quantity([np.nan, 1], unit=u.m / u.s)
         Vperp2 = u.Quantity([np.nan, 1], unit=u.m / u.s)  # an exact copy
         T_i = u.Quantity([1, np.nan], unit=u.K)
 
-        gyroradius(B_arr, "e-", Vperp=Vperp1, T_i=T_i)
+        gyroradius(B_arr, "e-", Vperp=Vperp1, T=T_i)
         assert_quantity_allclose(Vperp1, Vperp2)