Initalize package documentation

.github/workflows/ci.yml

@@ -70,6 +70,11 @@ jobs:
           python: '3.14'
           nox_session: build
 
+        - name: Documentation, Python 3.14, Ubuntu
+          os: ubuntu-latest
+          python: '3.14'
+          nox_session: docs
+
         - name: Check GitHub workflow security
           os: ubuntu-latest
           python: '3.14'

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_static/README.md

@@ -0,0 +1,3 @@
+## `docs/source/_static`
+
+Storage of static custom assets.

docs/source/conf.py

@@ -0,0 +1,27 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "pyFaradayCup"
+copyright = "2026, pyFaradayCup developers"  # ruff:ignore[A001]
+author = "pyFaradayCup developers"
+release = "0.1.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,10 @@
+pyFaradayCup
+============
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

noxfile.py

@@ -22,6 +22,7 @@
 """
 
 import os
+import pathlib
 
 import nox
 import nox.command
@@ -38,6 +39,8 @@
 RUNNING_ON_CI: bool = os.getenv("CI") is not None
 RUNNING_ON_RTD: bool = os.getenv("READTHEDOCS") is not None
 
+DOCPYTHON = "3.14"
+
 
 @nox_uv.session(uv_groups=["test"], python=SUPPORTED_PYTHON_VERSIONS)
 def tests(session: nox.Session) -> None:
@@ -46,6 +49,112 @@ def tests(session: nox.Session) -> None:
     session.run("pytest", *session.posargs)
 
 
+if RUNNING_ON_RTD:
+    rtd_output_path = pathlib.Path(os.environ.get("READTHEDOCS_OUTPUT")) / "html"  # ty:ignore[invalid-argument-type]
+    rtd_output_path.mkdir(parents=True, exist_ok=True)
+    doc_build_dir = str(rtd_output_path)
+else:
+    doc_build_dir = "docs/_build/html"
+
+
+SPHINX_BASE_COMMAND: list[str] = [
+    "sphinx-build",
+    "docs/source/",
+    doc_build_dir,
+    "--nitpicky",
+    "--keep-going",
+]
+
+if not RUNNING_ON_RTD:
+    SPHINX_BASE_COMMAND.extend(["--fail-on-warning"])
+
+BUILD_HTML: tuple[str, ...] = ("--builder", "html")
+CHECK_HYPERLINKS: tuple[str, ...] = ("--builder", "linkcheck")
+
+DOC_TROUBLESHOOTING_MESSAGE = """
+
+📘 Tips for troubleshooting common documentation build failures are in
+PlasmaPy's documentation guide at:
+
+🔗 https://docs.plasmapy.org/en/latest/contributing/doc_guide.html#troubleshooting
+"""
+
+
+@nox_uv.session(python=DOCPYTHON, uv_groups=["docs"])
+def docs(session: nox.Session) -> None:
+    """
+    Build documentation with Sphinx.
+
+    This session may require installation of pandoc and graphviz.
+
+    Configuration file: docs/source/conf.py
+    """
+    if RUNNING_ON_CI:
+        session.log(DOC_TROUBLESHOOTING_MESSAGE)
+
+    # Can we use pixi or conda to install graphviz and pandoc if they
+    # are not installed?
+
+    # session.run_install("dot", "-V", external=True)
+    # session.run_install("pandoc", "--version", external=True)
+
+    session.run(*SPHINX_BASE_COMMAND, *BUILD_HTML, *session.posargs)
+
+    landing_page = pathlib.Path(doc_build_dir) / "index.html"
+    if landing_page.exists():
+        session.log(f"The documentation may be previewed at {landing_page}")
+    else:
+        session.error(f"Documentation preview landing page not found: {landing_page}")
+
+
+# The following session was copied from PlasmaPy's noxfile.py, and will
+# be necessary for when we connect to Read the Docs.
+
+# @nox_uv.session(python=DOCPYTHON, uv_groups=["docs"])
+# def htmlzip(session: nox.Session) -> None:
+#     """Bundle documentation build into a zip file on Read the Docs."""
+#     if not RUNNING_ON_RTD:
+#         session.error("This session must be run on Read the Docs.")
+#
+#     html_build_dir = pathlib.Path(doc_build_dir)
+#     html_landing_page = (html_build_dir / "index.html").resolve()
+#     READTHEDOCS_OUTPUT = html_build_dir.parent
+#     if not html_landing_page.exists():
+#         session.error(
+#             f"No documentation build found at: {html_landing_page}\n"
+#             f"It appears the documentation has not been built.",
+#         )
+#
+#     command = [
+#         "sphinx-build",
+#         "--show-traceback",
+#         "--doctree-dir",
+#         f"{html_build_dir / '.doctrees'}",
+#         "--builder",
+#         "singlehtml",
+#         "--define",
+#         "language=en",
+#         "./docs/source",  # source directory
+#         f"{READTHEDOCS_OUTPUT / 'htmlzip'}",  # output directory
+#     ]
+#     session.run(*command)
+#
+#     # now build the zip file
+#     READTHEDOCS_PROJECT = os.environ.get("READTHEDOCS_PROJECT")
+#     READTHEDOCS_LANGUAGE = os.environ.get("READTHEDOCS_LANGUAGE")
+#     READTHEDOCS_VERSION = os.environ.get("READTHEDOCS_VERSION")
+#
+#     # mimic RTD default naming convention
+#     zip_name = f"{READTHEDOCS_PROJECT}-{READTHEDOCS_LANGUAGE}-{READTHEDOCS_VERSION}.zip"
+#
+#     cwd = pathlib.Path.cwd()
+#     session.chdir(f"{READTHEDOCS_OUTPUT / 'htmlzip'}")
+#     session.run("zip", "-r", "-m", f"{zip_name}", ".", external=True)
+#     session.chdir(f"{cwd}")
+#
+#     session.log(f"The htmlzip was placed in: {READTHEDOCS_OUTPUT / 'htmlzip'}")
+
+
 @nox_uv.session(uv_groups=["dev"])
 def typecheck(session: nox.Session) -> None:
     """Perform static type checking with ty."""

pyproject.toml

@@ -38,6 +38,9 @@ test = [
   "pytest-filter-subpackage>=0.2",
   "pytest-xdist>=3.8",
 ]
+docs = [
+  "sphinx>=9.1",
+]
 lint = [
   "pre-commit>=4.6.2",
 ]
@@ -76,7 +79,7 @@ lint.extend-select = [
   "C90",
   "COM",
   "D",
-  "DOC",    # in preview and not enabled as of August 2026
+  # "DOC",    # in preview and not enabled as of August 2026
   "DTZ",
   "E",
   "EM",