Fill out some basic documentation (#17)

* put install and import test into its own workflow

* add tests on py 3.6 and 3.13

* cache tests and set fetch-depth to 1

* restrict workflow permissions

* no not explicitly install plasmapy

* set upper sphinx limit to < 8.2

* set upper sphinx limit to < 7.4

* add plasmapy dependency to the documentation requirements

* set min python version to 3.8

* set min setuptools version to 61

* remove fail on warnings and add 3x verbosity

* remove the 3x verbosity

* add dependency "packaging"

* adopt a kwarg passing scheme so we can be flexible in passing args to generate_autosummary_content(), who's signature changes for sphinx >= 8.0

* put sphinx upper limit to 8.2

* add sphinx_limits workflow

* repair sphinx_limits workflow

* repair sphinx_limits workflow

* replace double quotes with single quotes

* put ${{ matrix.sphinx }} between quotes

* put fail on warning for the sphinx_limit workflow

* put fail on warning for the documentation workflow

* explicitly pass prefixes to import_by_name

* explicitly remove prefixes before passing to parent method

* add a nitpick exception for SphinxDirective.parse_inline

* remove the quiet tag from sphinx builds workflow

* add to nitpick exceptions

* remove the string prefix in a python agnostic way

* correct the prefix removal +1

* add nitpick ignore for ObjectMembers type annotation

* make nitpick ignore rules a little more generic

* add ObjectMember to nitpick ignore rules

* remove upper dependency limit on sphinx

* add a build on py3.11

* add kwargs for generate_autosummary_content() that are specific to sphinx >= 8.2 specific

* remove trailing whitespace

* add check on py3.11

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* modify docstring of plasmapy_sphinx.autodoc to it reads better when inserted into the docstring of plasmapy_sphinx.ext.autodoc

* add docstring to plasmapy_sphinx.ext.autodoc

* wrangle option :no-index: to :index: for sphinx < 7.2

* PEP 8 line length

* remove unused import

* remove wrongly placed handling of the no-index option for sphinx < 7.2

* add the 'no-index' option to option_spec if ModuleDocumenter.option_spec does not have it

* wrangle option :no-index: to :index: for sphinx < 7.2

* remove unused import

* fix typo

* remove unused import

* update docstrings for automodsumm

* update docstrings for css and directives

* add docstring for plasmapy_sphinx.theme

* plasmapy_sphinx.theme to the sidebar Extensions section

* remove admonition note about not being released on PyPI

* delete docs/first_steps/configure.rst

* rename Installing to Installation

* add noqa

* copy and modify installation instructions from plasmapy docs

* remove noqa

* add permissions statement

* remove if-clause for importing importlib.metadata

* Apply suggestions from code review

Co-authored-by: Nick Murphy <[email protected]>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Nick Murphy <[email protected]>

Author: 3 people

docs/first_steps/configure.rst

@@ -1,4 +1,130 @@
+.. _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
+.. _download Python: https://www.python.org/downloads
+.. _from PyPI: https://pypi.org/project/plasmapy_sphinx
+.. _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/first_steps/install.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

docs/index.rst

@@ -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/autodoc/__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/__init__.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/automodsumm/core.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/directives/__init__.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/autodoc.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/automodsumm.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