diff --git a/docs/source/conf.py b/docs/source/conf.py index 368ec8b..c4f89b7 100644 --- a/docs/source/conf.py +++ b/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 = [] diff --git a/docs/source/index.rst b/docs/source/index.rst index f322adb..1d77a06 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,3 +8,5 @@ documentation for details. .. toctree:: :maxdepth: 2 :caption: Contents: + + utils diff --git a/docs/source/utils.rst b/docs/source/utils.rst new file mode 100644 index 0000000..439d893 --- /dev/null +++ b/docs/source/utils.rst @@ -0,0 +1,11 @@ +.. _utils: + +================= +Package utilities +================= + +.. module:: pyfaradaycup.utils +.. currentmodule:: pyfaradaycup.utils + +.. automodapi:: pyfaradaycup.utils + :noindex: diff --git a/noxfile.py b/noxfile.py index fc0b1ee..9ecfbd8 100644 --- a/noxfile.py +++ b/noxfile.py @@ -46,7 +46,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: diff --git a/pyproject.toml b/pyproject.toml index be859cd..49564c6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,6 +27,7 @@ dependencies = [ [dependency-groups] dev = [ + { include-group = "docs" }, { include-group = "lint" }, { include-group = "nox" }, { include-group = "test" }, @@ -40,6 +41,8 @@ test = [ ] docs = [ "sphinx>=9.1", + "sphinx-copybutton>=0.5.2", + "sphinx-notfound-page>=1.1", ] lint = [ "pre-commit>=4.6.2", diff --git a/src/pyfaradaycup/__init__.py b/src/pyfaradaycup/__init__.py index 188e0be..a83ca36 100644 --- a/src/pyfaradaycup/__init__.py +++ b/src/pyfaradaycup/__init__.py @@ -1,9 +1,5 @@ -def hello() -> str: - """Check that docstrings are tested. +"""Faraday cup data pipeline and data analysis tools.""" - Examples - -------- - >>> 6 * 9 - 54 - """ - return "Hello from pyfaradaycup!" +__all__: list[str] = ["utils"] + +from pyfaradaycup import utils diff --git a/src/pyfaradaycup/utils/__init__.py b/src/pyfaradaycup/utils/__init__.py new file mode 100644 index 0000000..801aeab --- /dev/null +++ b/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 diff --git a/uv.lock b/uv.lock index 6a272d9..e5b7c86 100644 --- a/uv.lock +++ b/uv.lock @@ -1094,11 +1094,16 @@ dev = [ { name = "pytest" }, { name = "pytest-filter-subpackage" }, { name = "pytest-xdist" }, + { name = "sphinx" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-notfound-page" }, { name = "ty" }, { name = "zizmor" }, ] docs = [ { name = "sphinx" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-notfound-page" }, ] lint = [ { name = "pre-commit" }, @@ -1133,10 +1138,17 @@ dev = [ { name = "pytest", specifier = ">=9.1" }, { name = "pytest-filter-subpackage", specifier = ">=0.2" }, { name = "pytest-xdist", specifier = ">=3.8" }, + { name = "sphinx", specifier = ">=9.1" }, + { name = "sphinx-copybutton", specifier = ">=0.5.2" }, + { name = "sphinx-notfound-page", specifier = ">=1.1" }, { name = "ty", specifier = ">=0.0.74" }, { name = "zizmor", specifier = ">=1.29" }, ] -docs = [{ name = "sphinx", specifier = ">=9.1.0" }] +docs = [ + { name = "sphinx", specifier = ">=9.1" }, + { name = "sphinx-copybutton", specifier = ">=0.5.2" }, + { name = "sphinx-notfound-page", specifier = ">=1.1" }, +] lint = [{ name = "pre-commit", specifier = ">=4.6.2" }] nox = [ { name = "nox", specifier = ">=2026.8.10" }, @@ -1421,6 +1433,30 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/73/f7/b1884cb3188ab181fc81fa00c266699dab600f927a964df02ec3d5d1916a/sphinx-9.1.0-py3-none-any.whl", hash = "sha256:c84fdd4e782504495fe4f2c0b3413d6c2bf388589bb352d439b2a3bb99991978", size = 3921742, upload-time = "2025-12-31T15:09:25.561Z" }, ] +[[package]] +name = "sphinx-copybutton" +version = "0.5.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/fc/2b/a964715e7f5295f77509e59309959f4125122d648f86b4fe7d70ca1d882c/sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd", size = 23039, upload-time = "2023-04-14T08:10:22.998Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9e/48/1ea60e74949eecb12cdd6ac43987f9fd331156388dcc2319b45e2ebb81bf/sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e", size = 13343, upload-time = "2023-04-14T08:10:20.844Z" }, +] + +[[package]] +name = "sphinx-notfound-page" +version = "1.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6a/b2/67603444a8ee97b4a8ea71b0a9d6bab1727ed65e362c87e02f818ee57b8a/sphinx_notfound_page-1.1.0.tar.gz", hash = "sha256:913e1754370bb3db201d9300d458a8b8b5fb22e9246a816643a819a9ea2b8067", size = 7392, upload-time = "2025-01-28T18:45:02.871Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cd/d4/019fe439c840a7966012bbb95ccbdd81c5c10271749706793b43beb05145/sphinx_notfound_page-1.1.0-py3-none-any.whl", hash = "sha256:835dc76ff7914577a1f58d80a2c8418fb6138c0932c8da8adce4d9096fbcd389", size = 8167, upload-time = "2025-01-28T18:45:00.465Z" }, +] + [[package]] name = "sphinxcontrib-applehelp" version = "2.0.0"