From 87a8e50d7188ed41aba144540356695ffd7f76d4 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 18:20:25 -0400 Subject: [PATCH 01/13] Add commented out list of Sphinx extensions This comes from PlasmaPy --- docs/source/conf.py | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 368ec8b..fd72886 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,7 +14,35 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + # plasmapy extensions & setups + #"plasmapy_sphinx.theme", + #"plasmapy_sphinx.ext.autodoc", + #"plasmapy_sphinx.ext.directives", + # other 3rd party extensions + #"IPython.sphinxext.ipython_console_highlighting", + #"nbsphinx", + #"notfound.extension", + #"sphinx.ext.duration", + #"sphinx.ext.extlinks", + #"sphinx.ext.graphviz", + #"sphinx.ext.intersphinx", + #"sphinx.ext.mathjax", + #"sphinx.ext.napoleon", + #"sphinx.ext.todo", + #"sphinx.ext.viewcode", + #"sphinx_changelog", + #"sphinx_copybutton", + #"sphinx_gallery.load_style", + #"sphinx_issues", + #"sphinx_reredirects", + #"sphinx_tabs.tabs", + #"sphinx_toolbox.collapse", + #"sphinx_toolbox.rest_example", + #"sphinxcontrib.bibtex", + #"sphinxemoji.sphinxemoji", + #"sphinxcontrib.globalsubs", +] templates_path = ["_templates"] exclude_patterns = [] From 6b8e66019e727cc5397970747fa6bd4439107ec5 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:09:36 -0400 Subject: [PATCH 02/13] Enable first set of Sphinx extensions --- docs/source/conf.py | 36 ++++++------------- pyproject.toml | 3 ++ uv.lock | 84 ++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 96 insertions(+), 27 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index fd72886..85c76e1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,33 +15,17 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - # plasmapy extensions & setups - #"plasmapy_sphinx.theme", - #"plasmapy_sphinx.ext.autodoc", - #"plasmapy_sphinx.ext.directives", + # build-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 - #"IPython.sphinxext.ipython_console_highlighting", - #"nbsphinx", - #"notfound.extension", - #"sphinx.ext.duration", - #"sphinx.ext.extlinks", - #"sphinx.ext.graphviz", - #"sphinx.ext.intersphinx", - #"sphinx.ext.mathjax", - #"sphinx.ext.napoleon", - #"sphinx.ext.todo", - #"sphinx.ext.viewcode", - #"sphinx_changelog", - #"sphinx_copybutton", - #"sphinx_gallery.load_style", - #"sphinx_issues", - #"sphinx_reredirects", - #"sphinx_tabs.tabs", - #"sphinx_toolbox.collapse", - #"sphinx_toolbox.rest_example", - #"sphinxcontrib.bibtex", - #"sphinxemoji.sphinxemoji", - #"sphinxcontrib.globalsubs", + "notfound.extension", # adds a notfound page + "sphinx_copybutton", # adds a button that enables code to be copied ] templates_path = ["_templates"] diff --git a/pyproject.toml b/pyproject.toml index be859cd..531b432 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,6 +40,9 @@ test = [ ] docs = [ "sphinx>=9.1", + "sphinx-copybutton>=0.5.2", + "sphinx-notfound-page>=1.1.0", + "sphinxcontrib-bibtex>=2.7.0", ] lint = [ "pre-commit>=4.6.2", diff --git a/uv.lock b/uv.lock index 6a272d9..1e9947c 100644 --- a/uv.lock +++ b/uv.lock @@ -619,6 +619,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b5/91/53255615acd2a1eaca307ede3c90eb550bae9c94581f8c00081b6b1c8f44/kiwisolver-1.5.0-graalpy312-graalpy250_312_native-win_amd64.whl", hash = "sha256:1f1489f769582498610e015a8ef2d36f28f505ab3096d0e16b4858a9ec214f57", size = 75987, upload-time = "2026-03-09T13:15:39.65Z" }, ] +[[package]] +name = "latexcodec" +version = "3.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/27/dd/4270b2c5e2ee49316c3859e62293bd2ea8e382339d63ab7bbe9f39c0ec3b/latexcodec-3.0.1.tar.gz", hash = "sha256:e78a6911cd72f9dec35031c6ec23584de6842bfbc4610a9678868d14cdfb0357", size = 31222, upload-time = "2025-06-17T18:47:34.051Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b5/40/23569737873cc9637fd488606347e9dd92b9fa37ba4fcda1f98ee5219a97/latexcodec-3.0.1-py3-none-any.whl", hash = "sha256:a9eb8200bff693f0437a69581f7579eb6bca25c4193515c09900ce76451e452e", size = 18532, upload-time = "2025-06-17T18:47:30.726Z" }, +] + [[package]] name = "lmfit" version = "1.3.4" @@ -1059,6 +1068,32 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/45/e2/bbb7129c9e7999a6b8ee9cca3b66486c25c423ab5a75f34071798b74ce94/pre_commit-4.6.2-py2.py3-none-any.whl", hash = "sha256:e2dde9a75d3bce11bd3831c26d134df00a2803c1d818be6a0383c3dcda25dc4e", size = 226202, upload-time = "2026-08-10T22:07:16.942Z" }, ] +[[package]] +name = "pybtex" +version = "0.26.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "latexcodec" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/4d/f5/f30da9c93f0fa6d619332b2f69597219b625f35780473a05164a9981fd9a/pybtex-0.26.1.tar.gz", hash = "sha256:2e5543bea424e60e9e42eef70bff597be48649d8f68ba061a7a092b2477d5464", size = 692991, upload-time = "2026-04-03T13:05:39.014Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/44/f6/775eb92e865b28cdb4ad1f2bed7a5446197516f76b58a950faa3be3fd08d/pybtex-0.26.1-py3-none-any.whl", hash = "sha256:e26c0412cc54f5f21b2a6d9d175762a2d2af9ccf3a8f651cdb89ec035db77aa1", size = 126134, upload-time = "2026-04-03T13:05:40.623Z" }, +] + +[[package]] +name = "pybtex-docutils" +version = "1.0.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "pybtex" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7e/84/796ea94d26188a853660f81bded39f8de4cfe595130aef0dea1088705a11/pybtex-docutils-1.0.3.tar.gz", hash = "sha256:3a7ebdf92b593e00e8c1c538aa9a20bca5d92d84231124715acc964d51d93c6b", size = 18348, upload-time = "2023-08-22T18:47:54.833Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/11/b1/ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1/pybtex_docutils-1.0.3-py3-none-any.whl", hash = "sha256:8fd290d2ae48e32fcb54d86b0efb8d573198653c7e2447d5bec5847095f430b9", size = 6385, upload-time = "2023-08-22T06:43:20.513Z" }, +] + [[package]] name = "pyerfa" version = "2.0.1.5" @@ -1099,6 +1134,9 @@ dev = [ ] docs = [ { name = "sphinx" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-notfound-page" }, + { name = "sphinxcontrib-bibtex" }, ] lint = [ { name = "pre-commit" }, @@ -1136,7 +1174,12 @@ dev = [ { 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.0" }, + { name = "sphinxcontrib-bibtex", specifier = ">=2.7.0" }, +] lint = [{ name = "pre-commit", specifier = ">=4.6.2" }] nox = [ { name = "nox", specifier = ">=2026.8.10" }, @@ -1421,6 +1464,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" @@ -1430,6 +1497,21 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5d/85/9ebeae2f76e9e77b952f4b274c27238156eae7979c5421fba91a28f4970d/sphinxcontrib_applehelp-2.0.0-py3-none-any.whl", hash = "sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5", size = 119300, upload-time = "2024-07-29T01:08:58.99Z" }, ] +[[package]] +name = "sphinxcontrib-bibtex" +version = "2.7.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "pybtex" }, + { name = "pybtex-docutils" }, + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/15/6a/8e0b2c2420286389e7fed78ff361ec30e2f1d58c8560af8d64df5e7b61e0/sphinxcontrib_bibtex-2.7.0.tar.gz", hash = "sha256:fee700f7aae29bb8f654c62913f00d34ac44fc0b8ca0fa67ac922ff4453addee", size = 120669, upload-time = "2026-05-06T09:29:24.935Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/52/c0/d28e62407f4733bbe0169287bc012f0ac3b4a2021066b285570654119c8b/sphinxcontrib_bibtex-2.7.0-py3-none-any.whl", hash = "sha256:28cf0ec7a957d1c7548d5749317ed472ce877e1b629f430f88e3789aa51f87b1", size = 40287, upload-time = "2026-05-06T09:29:23.253Z" }, +] + [[package]] name = "sphinxcontrib-devhelp" version = "2.0.0" From 416edf90a2df30426297b542ef16bab9ab238458 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:13:53 -0400 Subject: [PATCH 03/13] Update extensions list --- docs/source/conf.py | 1 + pyproject.toml | 2 +- uv.lock | 52 --------------------------------------------- 3 files changed, 2 insertions(+), 53 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 85c76e1..0b0b811 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,6 +25,7 @@ "sphinx.ext.viewcode", # add links to highlighted source code # other 3rd party extensions "notfound.extension", # adds a notfound page + "sphinxcontrib.bibtex", # allows a bibliography via bibtex "sphinx_copybutton", # adds a button that enables code to be copied ] diff --git a/pyproject.toml b/pyproject.toml index 531b432..713ae96 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" }, @@ -42,7 +43,6 @@ docs = [ "sphinx>=9.1", "sphinx-copybutton>=0.5.2", "sphinx-notfound-page>=1.1.0", - "sphinxcontrib-bibtex>=2.7.0", ] lint = [ "pre-commit>=4.6.2", diff --git a/uv.lock b/uv.lock index 1e9947c..400ab82 100644 --- a/uv.lock +++ b/uv.lock @@ -619,15 +619,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b5/91/53255615acd2a1eaca307ede3c90eb550bae9c94581f8c00081b6b1c8f44/kiwisolver-1.5.0-graalpy312-graalpy250_312_native-win_amd64.whl", hash = "sha256:1f1489f769582498610e015a8ef2d36f28f505ab3096d0e16b4858a9ec214f57", size = 75987, upload-time = "2026-03-09T13:15:39.65Z" }, ] -[[package]] -name = "latexcodec" -version = "3.0.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/27/dd/4270b2c5e2ee49316c3859e62293bd2ea8e382339d63ab7bbe9f39c0ec3b/latexcodec-3.0.1.tar.gz", hash = "sha256:e78a6911cd72f9dec35031c6ec23584de6842bfbc4610a9678868d14cdfb0357", size = 31222, upload-time = "2025-06-17T18:47:34.051Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/b5/40/23569737873cc9637fd488606347e9dd92b9fa37ba4fcda1f98ee5219a97/latexcodec-3.0.1-py3-none-any.whl", hash = "sha256:a9eb8200bff693f0437a69581f7579eb6bca25c4193515c09900ce76451e452e", size = 18532, upload-time = "2025-06-17T18:47:30.726Z" }, -] - [[package]] name = "lmfit" version = "1.3.4" @@ -1068,32 +1059,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/45/e2/bbb7129c9e7999a6b8ee9cca3b66486c25c423ab5a75f34071798b74ce94/pre_commit-4.6.2-py2.py3-none-any.whl", hash = "sha256:e2dde9a75d3bce11bd3831c26d134df00a2803c1d818be6a0383c3dcda25dc4e", size = 226202, upload-time = "2026-08-10T22:07:16.942Z" }, ] -[[package]] -name = "pybtex" -version = "0.26.1" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "latexcodec" }, - { name = "pyyaml" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/4d/f5/f30da9c93f0fa6d619332b2f69597219b625f35780473a05164a9981fd9a/pybtex-0.26.1.tar.gz", hash = "sha256:2e5543bea424e60e9e42eef70bff597be48649d8f68ba061a7a092b2477d5464", size = 692991, upload-time = "2026-04-03T13:05:39.014Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/44/f6/775eb92e865b28cdb4ad1f2bed7a5446197516f76b58a950faa3be3fd08d/pybtex-0.26.1-py3-none-any.whl", hash = "sha256:e26c0412cc54f5f21b2a6d9d175762a2d2af9ccf3a8f651cdb89ec035db77aa1", size = 126134, upload-time = "2026-04-03T13:05:40.623Z" }, -] - -[[package]] -name = "pybtex-docutils" -version = "1.0.3" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "docutils" }, - { name = "pybtex" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/7e/84/796ea94d26188a853660f81bded39f8de4cfe595130aef0dea1088705a11/pybtex-docutils-1.0.3.tar.gz", hash = "sha256:3a7ebdf92b593e00e8c1c538aa9a20bca5d92d84231124715acc964d51d93c6b", size = 18348, upload-time = "2023-08-22T18:47:54.833Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/11/b1/ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1/pybtex_docutils-1.0.3-py3-none-any.whl", hash = "sha256:8fd290d2ae48e32fcb54d86b0efb8d573198653c7e2447d5bec5847095f430b9", size = 6385, upload-time = "2023-08-22T06:43:20.513Z" }, -] - [[package]] name = "pyerfa" version = "2.0.1.5" @@ -1136,7 +1101,6 @@ docs = [ { name = "sphinx" }, { name = "sphinx-copybutton" }, { name = "sphinx-notfound-page" }, - { name = "sphinxcontrib-bibtex" }, ] lint = [ { name = "pre-commit" }, @@ -1178,7 +1142,6 @@ docs = [ { name = "sphinx", specifier = ">=9.1" }, { name = "sphinx-copybutton", specifier = ">=0.5.2" }, { name = "sphinx-notfound-page", specifier = ">=1.1.0" }, - { name = "sphinxcontrib-bibtex", specifier = ">=2.7.0" }, ] lint = [{ name = "pre-commit", specifier = ">=4.6.2" }] nox = [ @@ -1497,21 +1460,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5d/85/9ebeae2f76e9e77b952f4b274c27238156eae7979c5421fba91a28f4970d/sphinxcontrib_applehelp-2.0.0-py3-none-any.whl", hash = "sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5", size = 119300, upload-time = "2024-07-29T01:08:58.99Z" }, ] -[[package]] -name = "sphinxcontrib-bibtex" -version = "2.7.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "docutils" }, - { name = "pybtex" }, - { name = "pybtex-docutils" }, - { name = "sphinx" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/15/6a/8e0b2c2420286389e7fed78ff361ec30e2f1d58c8560af8d64df5e7b61e0/sphinxcontrib_bibtex-2.7.0.tar.gz", hash = "sha256:fee700f7aae29bb8f654c62913f00d34ac44fc0b8ca0fa67ac922ff4453addee", size = 120669, upload-time = "2026-05-06T09:29:24.935Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/52/c0/d28e62407f4733bbe0169287bc012f0ac3b4a2021066b285570654119c8b/sphinxcontrib_bibtex-2.7.0-py3-none-any.whl", hash = "sha256:28cf0ec7a957d1c7548d5749317ed472ce877e1b629f430f88e3789aa51f87b1", size = 40287, upload-time = "2026-05-06T09:29:23.253Z" }, -] - [[package]] name = "sphinxcontrib-devhelp" version = "2.0.0" From 3167cfb830b5b0867eb556aa069691f3452b184d Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:14:21 -0400 Subject: [PATCH 04/13] pre-commit --- docs/source/conf.py | 2 +- pyproject.toml | 2 +- uv.lock | 8 +++++++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0b0b811..b2776da 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,7 +15,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - # build-in 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 diff --git a/pyproject.toml b/pyproject.toml index 713ae96..49564c6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,7 +42,7 @@ test = [ docs = [ "sphinx>=9.1", "sphinx-copybutton>=0.5.2", - "sphinx-notfound-page>=1.1.0", + "sphinx-notfound-page>=1.1", ] lint = [ "pre-commit>=4.6.2", diff --git a/uv.lock b/uv.lock index 400ab82..e5b7c86 100644 --- a/uv.lock +++ b/uv.lock @@ -1094,6 +1094,9 @@ dev = [ { name = "pytest" }, { name = "pytest-filter-subpackage" }, { name = "pytest-xdist" }, + { name = "sphinx" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-notfound-page" }, { name = "ty" }, { name = "zizmor" }, ] @@ -1135,13 +1138,16 @@ 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" }, { name = "sphinx-copybutton", specifier = ">=0.5.2" }, - { name = "sphinx-notfound-page", specifier = ">=1.1.0" }, + { name = "sphinx-notfound-page", specifier = ">=1.1" }, ] lint = [{ name = "pre-commit", specifier = ">=4.6.2" }] nox = [ From 87017cc1cb47a5382fd26754f26c77c4f147a2f8 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:16:09 -0400 Subject: [PATCH 05/13] Remove sphinxcontrib-bibtex for now --- docs/source/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b2776da..ed96c7a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,7 +25,6 @@ "sphinx.ext.viewcode", # add links to highlighted source code # other 3rd party extensions "notfound.extension", # adds a notfound page - "sphinxcontrib.bibtex", # allows a bibliography via bibtex "sphinx_copybutton", # adds a button that enables code to be copied ] From a9b5be4526b73586f19f0313febf6016ebd04303 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:22:43 -0400 Subject: [PATCH 06/13] Add docstring and __all__ to top __init__.py --- src/pyfaradaycup/__init__.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/pyfaradaycup/__init__.py b/src/pyfaradaycup/__init__.py index 188e0be..becd2d0 100644 --- a/src/pyfaradaycup/__init__.py +++ b/src/pyfaradaycup/__init__.py @@ -1,3 +1,8 @@ +"""Faraday cup data pipeline and data analysis tools.""" + +__all__: list[str] = ["hello"] + + def hello() -> str: """Check that docstrings are tested. From 68e344d522bfc7a1acfbf8c9ae1245f661766cfd Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:34:41 -0400 Subject: [PATCH 07/13] Update comment --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ed96c7a..c4f89b7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,7 +24,7 @@ "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 page + "notfound.extension", # adds a notfound 404 page "sphinx_copybutton", # adds a button that enables code to be copied ] From bf622159b996e6bd3100fd1af27fb90aa017cac2 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:36:03 -0400 Subject: [PATCH 08/13] Add utils subpackage --- src/pyfaradaycup/utils/__init__.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 src/pyfaradaycup/utils/__init__.py diff --git a/src/pyfaradaycup/utils/__init__.py b/src/pyfaradaycup/utils/__init__.py new file mode 100644 index 0000000..e9af3c2 --- /dev/null +++ b/src/pyfaradaycup/utils/__init__.py @@ -0,0 +1,17 @@ +"""Package utilities.""" + +__all__: list[str] = ["placeholder"] + +from typing import Literal + + +def placeholder(x: int) -> Literal[42]: + """ + Run a placeholder function. + + Examples + -------- + >>> placeholder(1) # intentional failure + 43 + """ + return 42 From bbec37459a9ed2cc86a9ab0952395038f030f7da Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:36:17 -0400 Subject: [PATCH 09/13] Enable doctests for most recent version of Python --- noxfile.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) 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: From 6ad1aec2c2291fbc7814a6053c9cebd7430faa03 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 19:37:00 -0400 Subject: [PATCH 10/13] Remove placeholder function from top-level __init__.py --- src/pyfaradaycup/__init__.py | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/src/pyfaradaycup/__init__.py b/src/pyfaradaycup/__init__.py index becd2d0..a83ca36 100644 --- a/src/pyfaradaycup/__init__.py +++ b/src/pyfaradaycup/__init__.py @@ -1,14 +1,5 @@ """Faraday cup data pipeline and data analysis tools.""" -__all__: list[str] = ["hello"] +__all__: list[str] = ["utils"] - -def hello() -> str: - """Check that docstrings are tested. - - Examples - -------- - >>> 6 * 9 - 54 - """ - return "Hello from pyfaradaycup!" +from pyfaradaycup import utils From 34de28db2d7f1aa2946ccb659b27299577a8c706 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 20:01:28 -0400 Subject: [PATCH 11/13] Remove intentional error in utils.placeholder I put the error in to make sure that doctests were being run. --- src/pyfaradaycup/utils/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pyfaradaycup/utils/__init__.py b/src/pyfaradaycup/utils/__init__.py index e9af3c2..801aeab 100644 --- a/src/pyfaradaycup/utils/__init__.py +++ b/src/pyfaradaycup/utils/__init__.py @@ -5,13 +5,13 @@ from typing import Literal -def placeholder(x: int) -> Literal[42]: +def placeholder() -> Literal[42]: """ Run a placeholder function. Examples -------- - >>> placeholder(1) # intentional failure - 43 + >>> placeholder() + 42 """ return 42 From e529e4251ffdd37d0f39e84608d90c6d0ad27045 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 20:49:14 -0400 Subject: [PATCH 12/13] Add docs/source/utils.rst --- docs/source/utils.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/source/utils.rst 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: From ad1c62f984bfcf73c94c11fb88ff4da328efcbef Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Sep 2026 20:49:26 -0400 Subject: [PATCH 13/13] Add utils.rst to toctree --- docs/source/index.rst | 2 ++ 1 file changed, 2 insertions(+) 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