Enable documentation build extensions

docs/source/conf.py

@@ -14,7 +14,19 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    # built-in extensions
+    "sphinx.ext.apidoc",  # generate API docs
+    "sphinx.ext.autodoc",  # include documentation from docstrings
+    "sphinx.ext.duration",  # show durations in documentation builds
+    "sphinx.ext.intersphinx",  # link to other projects' documentation
+    "sphinx.ext.mathjax",  # render math with MathJax
+    "sphinx.ext.napoleon",  # support numpy and google style docstrings
+    "sphinx.ext.viewcode",  # add links to highlighted source code
+    # other 3rd party extensions
+    "notfound.extension",  # adds a notfound 404 page
+    "sphinx_copybutton",  # adds a button that enables code to be copied
+]
 
 templates_path = ["_templates"]
 exclude_patterns = []

docs/source/index.rst

@@ -8,3 +8,5 @@ documentation for details.
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+
+   utils

docs/source/utils.rst

@@ -0,0 +1,11 @@
+.. _utils:
+
+=================
+Package utilities
+=================
+
+.. module:: pyfaradaycup.utils
+.. currentmodule:: pyfaradaycup.utils
+
+.. automodapi:: pyfaradaycup.utils
+   :noindex:

noxfile.py

@@ -53,7 +53,12 @@
 def tests(session: nox.Session) -> None:
     """Run tests with pytest."""
     session.install(".")
-    session.run("pytest", *session.posargs)
+
+    # Test examples in docstrings only using the most recent Python
+    # because string representations may change.
+    doctest_options = ["--doctest-modules"] if session.python == MAXPYTHON else []
+
+    session.run("pytest", *doctest_options, *session.posargs)
 
 
 if RUNNING_ON_RTD:

pyproject.toml

@@ -1,3 +1,3 @@
 [build-system]
 build-backend = "uv_build"
 requires = [ "uv-build>=0.12.5,<0.13" ]
@@ -61,6 +61,7 @@
 
 [dependency-groups]
 dev = [
+  { include-group = "docs" },
   { include-group = "lint" },
   { include-group = "nox" },
   { include-group = "test" },
@@ -74,6 +75,8 @@
 ]
 docs = [
   "sphinx",
+  "sphinx-copybutton",
+  "sphinx-notfound-page",
 ]
 lint = [
   "pre-commit",

src/pyfaradaycup/__init__.py

@@ -1,12 +1,11 @@
+"""Faraday cup data pipeline and data analysis tools."""
 from pyfaradaycup import pipeline
-
+from pyfaradaycup import utils
 
 def hello() -> str:
     """Check that docstrings are tested.
 
-    Examples
-    --------
-    >>> 6 * 9
-    54
-    """
-    return "Hello from pyfaradaycup!"
+
+__all__: list[str] = ["utils"]
+
+

src/pyfaradaycup/utils/__init__.py

@@ -0,0 +1,17 @@
+"""Package utilities."""
+
+__all__: list[str] = ["placeholder"]
+
+from typing import Literal
+
+
+def placeholder() -> Literal[42]:
+    """
+    Run a placeholder function.
+
+    Examples
+    --------
+    >>> placeholder()
+    42
+    """
+    return 42