Fill out some basic documentation

docs/first_steps/install.rst

@@ -1,4 +1,131 @@
+.. _plasmapy-install:
+
+.. |minpython| replace:: 3.8
+
+.. _git: https://git-scm.com/
+.. |git| replace:: git_
+
+.. _pip: https://pip.pypa.io
+.. |pip| replace:: pip_
+
+.. _Python: https://www.python.org/
+.. |Python| replace:: Python_
+
+.. _PyPI: https://pypi.org/
+.. |PyPI| replace:: PyPI_
+
+.. _`Github repository`: https://github.com/PlasmaPy/plasmapy_sphinx
+.. |Github repository| replace:: `Github repository`_
+
+.. role:: py(code)
+    :language: python
+
+.. role:: bash(code)
+   :language: bash
+
+****************************
 Installing `plasmapy_sphinx`
-============================
+****************************
+
+`plasmapy_sphinx` requires a minimum |Python| version of |minpython|. If
+you do not have |Python| installed already, here are the instructions
+to `download Python`_ and install it. 🐍
+
+.. contents:: Contents
+   :local:
+
+.. _install-pip:
+
+Installing with pip
+===================
+
+To install the most recent release of `plasmapy_sphinx` on |PyPI| with
+|pip| into an existing |Python| |minpython|\ + environment on macOS or
+Linux, open a terminal and run:
+
+.. code-block:: bash
+
+   python -m pip install plasmapy
+
+On some systems, it might be necessary to specify the |Python| version
+number by using ``python3``, ``python3.8``, ``python3.9``,
+``python3.10``, or ``python3.11`` instead of ``python``.
+
+To install PlasmaPy on Windows, run:
+
+.. code-block:: bash
+
+   py -3.11 -m pip install plasmapy
+
+The version of |Python| may be changed from ``3.11`` to another supported
+Python |minpython|\ + release that has been installed on your computer.
+
+For more detailed information, please refer to this tutorial on
+`installing packages`_.
+
+Installing from source code
+===========================
+
+Obtaining official releases
+---------------------------
+
+A ZIP_ file containing the source code for official releases of
+`plasmapy_sphinx` can be obtained `from PyPI`_.
+
+Alternatively, official releases can be downloaded from the releases_
+page on the |GitHub repository|.
+
+Obtaining source code from GitHub
+---------------------------------
+
+If you have |git| installed on your computer, you may clone the
+|Github repository| and access the source code from the most
+recent development version by running:
+
+.. code-block:: bash
+
+   git clone https://github.com/PlasmaPy/plasmapy_sphinx.git
+
+The repository will be cloned inside a new subdirectory called
+:file:`plasmapy_sphinx`.
+
+If you do not have |git| installed on your computer, then you may
+download the most recent source code from |Github repository|
+by going to :guilabel:`Code` and selecting :guilabel:`Download ZIP`.
+`Unzipping <https://www.wikihow.com/Unzip-a-File>`__ the file will
+create a subdirectory called :file:`plasmapy_sphinx` that contains the
+source code.
+
+Building and installing
+-----------------------
+
+To install the downloaded version of `plasmapy_sphinx`, enter the
+:file:`plasmapy_sphinx` directory and run:
+
+.. code-block:: bash
+
+   pip install .
+
+If you expect to occasionally edit the source code, instead run:
+
+.. code-block:: bash
+
+   pip install -e .
+
+The ``-e`` flag makes the installation editable.
+
+.. note::
+
+   If you noticed any places where the installation instructions could
+   be improved or have become out of date, please `create an issue`_ on
+   |Github repository|. It would really help!
 
-blah
+.. _clone a repository using SSH: https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-ssh-urls
+.. _create an issue: https://github.com/PlasmaPy/plasmapy_sphinx/issues/new/choose
+.. _download Python: https://www.python.org/downloads
+.. _from PyPI: https://pypi.org/project/plasmapy_sphinx
+.. _from Zenodo: https://doi.org/10.5281/zenodo.6774349
+.. _installing packages: https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-from-vcs
+.. _releases: https://github.com/PlasmaPy/plasmapy_sphinx/releases
+.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer
+.. _ZIP: https://en.wikipedia.org/wiki/ZIP_(file_format)

docs/index.rst

@@ -15,22 +15,15 @@ just a selection of desired ones.
 
 .. note::
 
-    `plasmapy_sphinx` is not currently released in any form and can
-    only be installed directly from its `GitHub repository
-    <https://github.com/plasmapy/plasmapy_sphinx>`__.  We do plan to
-    release it to https://pypi.org but there is no scheduled release
-    date at this time.
-
-    Additionally, this package currently has no tests covering its
+    This package currently has no tests covering its
     functionality.
 
 
 .. toctree::
     :caption: First Steps
     :maxdepth: 1
 
-    Installing <first_steps/install>
-    Configuring <first_steps/configure>
+    Installation <first_steps/install>
 
 .. toctree::
     :caption: Extensions
@@ -40,6 +33,7 @@ just a selection of desired ones.
     api_static/plasmapy_sphinx.ext.automodsumm
     api_static/plasmapy_sphinx.ext.css
     api_static/plasmapy_sphinx.ext.directives
+    api_static/plasmapy_sphinx.theme
 
 .. toctree::
     :caption: Contributor Guide

plasmapy_sphinx/autodoc/__init__.py

@@ -1,5 +1,6 @@
 """
-This sub-package contains functionality that extends `sphinx.ext.autodoc`.
+`plasmapy_sphinx.autodoc` contains functionality that extends
+`sphinx.ext.autodoc`.
 
 *This functionality was highly influenced by and adapted from*
 `sphinx.ext.autodoc` *and* `sphinx_automodapi.automodapi`.

plasmapy_sphinx/automodsumm/__init__.py

@@ -1,10 +1,10 @@
 """
-This sub-package contains functionality that defines the :rst:dir:`automodsumm`
-directive and the
+`plasmapy_sphinx.automodsumm` contains functionality that defines the
+:rst:dir:`automodsumm` directive, and the associated automatic
 `stub file generation
 <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
 #sphinx-autogen-generate-autodoc-stub-pages>`_
-for items listed in :rst:dir:`automodsumm` tables.
+for the documented items in the generated :rst:dir:`automodsumm` tables.
 
 *This functionality was highly influenced by and adapted from*
 `sphinx.ext.autosummary` *and* `sphinx_automodapi.automodsumm`.

plasmapy_sphinx/automodsumm/core.py

@@ -283,16 +283,17 @@ def __init__(
             Instance of the sphinx application.
 
         modname : `str`
-            Name of the module given in the :rst:dir:`automodsumm` directive.  This
-            is the module to be inspected and have it's objects grouped.
+            Name of the module given in the :rst:dir:`automodsumm`
+            directive.  This is the module to be inspected and have
+            its objects grouped.
 
         options : Dict[str, Any]
-            Dictionary of options given for the :rst:dir:`automodsumm` directive
-            declaration.
+            Dictionary of options given for the :rst:dir:`automodsumm`
+            directive declaration.
 
         docname : str
-            Name of the document/file where the :rst:dir:`automodsumm` direction
-            was declared.
+            Name of the document/file where the :rst:dir:`automodsumm`
+            direction was declared.
         """
 
         self._app = app
@@ -609,8 +610,9 @@ def run(self):
 
     def option_processor(self):
         """
-        Instance of `~plasmapy_sphinx.automodsumm.core.Automodsumm` so further processing
-        (beyond :attr:`option_spec`) of directive options can be performed.
+        Instance of `~plasmapy_sphinx.automodsumm.core.Automodsumm` so
+        further processing (beyond :attr:`option_spec`) of directive
+        options can be performed.
         """
         processor = AutomodsummOptions(
             app=self.env.app,

plasmapy_sphinx/directives/__init__.py

@@ -1,5 +1,5 @@
 """
-This sub-package defines
+`plasmapy_sphinx.directives` defines
 `directives
 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
 and

plasmapy_sphinx/ext/autodoc.py

@@ -1,11 +1,22 @@
+"""
+This module is a `Sphinx extension
+<https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_
+that exposes the functionality of `plasmapy_sphinx.autodoc`.
+
+.. automodapi:: plasmapy_sphinx.autodoc
+   :no-index:
+   :no-groups:
+
+"""
+__all__ = ["automodapi", "setup"]
 from sphinx.application import Sphinx
 
 from plasmapy_sphinx.autodoc import automodapi
 
 
 def setup(app: Sphinx):
     """
-    Sphinx ``setup()`` function for setting up all of the
+    Sphinx ``setup()`` function for setting up all the
     `plasmapy_sphinx.autodoc` functionality, this includes
     `plasmapy_sphinx.automodsumm` functionality.
     """

plasmapy_sphinx/ext/automodsumm.py

@@ -1,3 +1,13 @@
+"""
+This module is a `Sphinx extension
+<https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_
+that exposes the functionality of `plasmapy_sphinx.automodsumm`.
+
+.. automodapi:: plasmapy_sphinx.automodsumm
+   :no-index:
+   :no-groups:
+
+"""
 from sphinx.application import Sphinx
 
 from plasmapy_sphinx.automodsumm import core

plasmapy_sphinx/ext/css.py

@@ -1,3 +1,12 @@
+"""
+This module is a `Sphinx extension
+<https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_
+that adds the PlasmaPy CSS style sheet to the `sphinx` build
+environment.  The :file:`plasmapy.css` is loaded into the build system
+using `~sphinx.application.Sphinx.add_css_file` with a priority of
+``501``.
+"""
+
 from sphinx.application import Sphinx
 
 from plasmapy_sphinx.utils import static_dir, css_dir

plasmapy_sphinx/ext/directives.py

@@ -1,3 +1,13 @@
+"""
+This module is a `Sphinx extension
+<https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_
+that exposes the functionality of `plasmapy_sphinx.directives`.
+
+.. automodapi:: plasmapy_sphinx.directives
+   :no-index:
+   :no-groups:
+
+"""
 from sphinx.application import Sphinx
 
 from plasmapy_sphinx.directives import confval, event

plasmapy_sphinx/theme/__init__.py

@@ -1,5 +1,20 @@
 # Sphinx Guide to Theme Development
 # https://www.sphinx-doc.org/en/master/development/theming.html
+"""
+The PlasmaPy theme is a `Sphinx theme
+<https://www.sphinx-doc.org/en/master/usage/theming.html>`_ that
+inherits from the `sphinx_rtd_theme`.  As such, it shares all the same
+`configuration values supported by sphinx_rtd_theme
+<https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#theme-options>`_\ .
+
+To use the PlasmaPy theme one needs to the :file:`conf.py`:
+
+.. code-block:: python
+
+    extensions = ["plasmapy_sphinx.theme"]
+    html_theme = "plasmapy_theme"
+
+"""
 __all__ = ["setup"]
 from sphinx.application import Sphinx