diff --git a/docs/first_steps/configure.rst b/docs/first_steps/configure.rst deleted file mode 100644 index 7fdf4d6..0000000 --- a/docs/first_steps/configure.rst +++ /dev/null @@ -1,4 +0,0 @@ -Configuring Your ``conf.py`` -============================ - -blah diff --git a/docs/first_steps/install.rst b/docs/first_steps/install.rst index 2b5e7a1..097b449 100644 --- a/docs/first_steps/install.rst +++ b/docs/first_steps/install.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 `__ 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) diff --git a/docs/index.rst b/docs/index.rst index 8ec4667..4939a75 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,13 +15,7 @@ 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 - `__. 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. @@ -29,8 +23,7 @@ just a selection of desired ones. :caption: First Steps :maxdepth: 1 - Installing - Configuring + Installation .. 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 diff --git a/plasmapy_sphinx/autodoc/__init__.py b/plasmapy_sphinx/autodoc/__init__.py index 78c7aab..e8c4b6b 100644 --- a/plasmapy_sphinx/autodoc/__init__.py +++ b/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`. diff --git a/plasmapy_sphinx/automodsumm/__init__.py b/plasmapy_sphinx/automodsumm/__init__.py index 20dc2f3..c716b8d 100644 --- a/plasmapy_sphinx/automodsumm/__init__.py +++ b/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 `_ -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`. diff --git a/plasmapy_sphinx/automodsumm/core.py b/plasmapy_sphinx/automodsumm/core.py index 1090b8e..3ee40dd 100644 --- a/plasmapy_sphinx/automodsumm/core.py +++ b/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, diff --git a/plasmapy_sphinx/directives/__init__.py b/plasmapy_sphinx/directives/__init__.py index 681fcf3..556b370 100644 --- a/plasmapy_sphinx/directives/__init__.py +++ b/plasmapy_sphinx/directives/__init__.py @@ -1,5 +1,5 @@ """ -This sub-package defines +`plasmapy_sphinx.directives` defines `directives `_ and diff --git a/plasmapy_sphinx/ext/autodoc.py b/plasmapy_sphinx/ext/autodoc.py index f9ebadc..9d62b91 100644 --- a/plasmapy_sphinx/ext/autodoc.py +++ b/plasmapy_sphinx/ext/autodoc.py @@ -1,3 +1,14 @@ +""" +This module is a `Sphinx extension +`_ +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 @@ -5,7 +16,7 @@ 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. """ diff --git a/plasmapy_sphinx/ext/automodsumm.py b/plasmapy_sphinx/ext/automodsumm.py index 6e423b4..6286f8d 100644 --- a/plasmapy_sphinx/ext/automodsumm.py +++ b/plasmapy_sphinx/ext/automodsumm.py @@ -1,3 +1,13 @@ +""" +This module is a `Sphinx extension +`_ +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 diff --git a/plasmapy_sphinx/ext/css.py b/plasmapy_sphinx/ext/css.py index 2ef77a9..82a2516 100644 --- a/plasmapy_sphinx/ext/css.py +++ b/plasmapy_sphinx/ext/css.py @@ -1,3 +1,12 @@ +""" +This module is a `Sphinx extension +`_ +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 diff --git a/plasmapy_sphinx/ext/directives.py b/plasmapy_sphinx/ext/directives.py index 1485bf7..d07b917 100644 --- a/plasmapy_sphinx/ext/directives.py +++ b/plasmapy_sphinx/ext/directives.py @@ -1,3 +1,13 @@ +""" +This module is a `Sphinx extension +`_ +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 diff --git a/plasmapy_sphinx/theme/__init__.py b/plasmapy_sphinx/theme/__init__.py index fdb54ae..a763a8d 100644 --- a/plasmapy_sphinx/theme/__init__.py +++ b/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 +`_ that +inherits from the `sphinx_rtd_theme`. As such, it shares all the same +`configuration values supported by sphinx_rtd_theme +`_\ . + +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