Merge pull request #1 from namurphy/pre-summer-school

Update repository infrastructure prior to summer school

.github/workflows/README.md

@@ -0,0 +1,16 @@
+# GitHub workflows
+
+[GitHub Actions]: https://docs.github.com/en/actions
+[Nox]: https://nox.thea.codes
+[YAML]: https://en.wikipedia.org/wiki/YAML
+
+The [`.github/workflows`](.) directory contains [YAML] files that
+describe [GitHub Actions] workflows such as those used to perform
+continuous integration tests.
+
+Several of the workflows invoke [Nox] sessions that are defined in the
+top-level [`noxfile.py`](../../noxfile.py).
+
+Continuous integration (CI) workflows include:
+
+ - [`ci.yml`](./ci.yml) — perform CI checks during pull requests (PRs)

.github/workflows/ci.yml

@@ -31,17 +31,17 @@ jobs:
       matrix:
         include:
 
-        - name: Tests, Python 3.12, Ubuntu
+        - name: Tests
           os: ubuntu-latest
           python: '3.12'
           nox_session: tests
 
-        - name: Documentation, Python 3.12, Ubuntu
+        - name: Documentation
           os: ubuntu-latest
           python: '3.12'
           nox_session: docs
 
-        - name: Packaging, Python 3.12, Ubuntu
+        - name: Packaging
           os: ubuntu-latest
           python: '3.12'
           nox_session: build

.pre-commit-config.yaml

@@ -8,16 +8,8 @@ repos:
   hooks:
   - id: check-ast
     name: validate Python code
-  - id: check-merge-conflict
-    name: check for git merge conflicts
     exclude: .*\.rst
   - id: check-case-conflict
-    name: check for filename case conflicts
-  - id: trailing-whitespace
-  - id: end-of-file-fixer
-  - id: check-json
-  - id: check-toml
-  - id: check-yaml
 
 - repo: https://github.com/python-jsonschema/check-jsonschema
   rev: 0.28.6
@@ -35,16 +27,6 @@ repos:
   hooks:
   - id: rst-directive-colons
   - id: rst-inline-touching-normal
-  - id: text-unicode-replacement-char
-
-- repo: https://github.com/codespell-project/codespell
-  rev: v2.3.0
-  hooks:
-  - id: codespell
-    name: codespell (add false positives to pyproject.toml)
-    args: [--write-changes]
-    additional_dependencies:
-    - tomli
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
   rev: v0.5.0

.readthedocs.yaml

@@ -15,4 +15,6 @@ sphinx:
 
 python:
   install:
+  - method: pip
+    path: .
   - requirements: docs/requirements.txt

docs/README.md

@@ -0,0 +1,49 @@
+# Documentation directory
+
+[**documentation guide**]: https://docs.plasmapy.org/en/latest/contributing/doc_guide.html
+[Sphinx]: https://www.sphinx-doc.org
+[Nox]: https://nox.thea.codes
+[Read the Docs]: https://about.readthedocs.com
+[reStructuredText]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer
+[`docs`]: .
+[`docs/source/conf.py`]: conf.py
+[install graphviz]: https://graphviz.org/download
+[install pandoc]: https://pandoc.org/installing.html
+
+> [!TIP]
+> To learn more about writing documentation, please check out the
+> [**documentation guide**].
+
+The [`docs`] directory contains the source files for the narrative
+documentation. The configuration file is [`docs/source/conf.py`].
+
+The documentation is written in [reStructuredText], built using
+[Sphinx] via a [Nox] session, and hosted by [Read the Docs].
+
+## Building documentation
+
+> [!TIP]
+> When making a pull request, the documentation can be previewed by
+> clicking on *Details* next to **docs/readthedocs.org** in the
+> list of checks.
+
+Prior to building documentation locally, please install [Nox] and its
+dependencies with:
+
+```shell
+python -m pip install nox uv
+```
+
+> [!NOTE]
+> It may also be necessary to [install pandoc] (and possibly [install graphviz])
+> if you want to build the documentation locally.
+
+The documentation can be built by going to the top-level directory of
+your clone of PlasmaPy and running:
+
+```shell
+nox -s docs
+```
+
+The documentation preview will be built in `docs/build/html` in your
+local clone of this repository.

docs/source/conf.py

@@ -9,7 +9,7 @@
 project = "hack"
 copyright = "2024, PlasmaPy Community"
 author = "PlasmaPy Community"
-release = "0.1.0"
+release = "2024.7.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -21,6 +21,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx_automodapi.automodapi",
+    "nbsphinx",
 ]
 
 exclude_patterns = []

docs/source/examples.rst

@@ -0,0 +1,19 @@
+.. _examples:
+
+Examples
+========
+
+This page provides a gallery of example notebooks.
+
+.. contents::
+   :local:
+
+
+Tutorials
+---------
+
+.. nbgallery::
+   :glob:
+
+   notebooks/astropy-units-completed
+   notebooks/particles-formulary-completed

docs/source/index.rst

@@ -2,14 +2,14 @@ PlasmaPy Summer School 2024 Documentation
 =========================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    densities
    frequencies
    lengths
    speeds
-
+   examples
 
 Indices and tables
 ==================