From a1e9d1a0f1a205f078575bc9124cbf71be5a90ae Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 11:38:03 -0500 Subject: [PATCH 01/10] build docs on python 3.13 --- docs/rtd_environment.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rtd_environment.yaml b/docs/rtd_environment.yaml index 31aa96589..bacbf8484 100644 --- a/docs/rtd_environment.yaml +++ b/docs/rtd_environment.yaml @@ -3,7 +3,7 @@ channels: - conda-forge - defaults dependencies: - - python=3.11 + - python=3.13 - pip - graphviz - furo From f746f4acd60b2491a8d11f05e8b2239006f0c4bb Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 12:47:24 -0500 Subject: [PATCH 02/10] fix code block for sphinx 9 --- docs/asdf/arrays.rst | 46 ++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/asdf/arrays.rst b/docs/asdf/arrays.rst index 8236458fa..4ae60f44c 100644 --- a/docs/asdf/arrays.rst +++ b/docs/asdf/arrays.rst @@ -211,29 +211,29 @@ to numpy arrays stored in ASDF: .. doctest-skip:: - import csv - import numpy as np - from asdf import AsdfFile - from asdf.tags.core import Stream - - tree = { - # We happen to know in advance that each row in the CSV has 100 ints - 'data': Stream([100], np.int64) - } - - ff = AsdfFile(tree) - # open the output file handle - with open('new_file.asdf', 'wb') as fd: - ff.write_to(fd) - # open the CSV file to be converted - with open('large_file.csv', 'r') as cfd: - # read each line of the CSV file - reader = csv.reader(cfd) - for row in reader: - # convert each row to a numpy array - array = np.array([int(x) for x in row], np.int64) - # write the array to the output file handle - fd.write(array.tobytes()) + >>> import csv + >>> import numpy as np + >>> from asdf import AsdfFile + >>> from asdf.tags.core import Stream + + >>> tree = { + >>> # We happen to know in advance that each row in the CSV has 100 ints + >>> 'data': Stream([100], np.int64) + >>> } + + >>> ff = AsdfFile(tree) + >>> # open the output file handle + >>> with open('new_file.asdf', 'wb') as fd: + >>> ff.write_to(fd) + >>> # open the CSV file to be converted + >>> with open('large_file.csv', 'r') as cfd: + >>> # read each line of the CSV file + >>> reader = csv.reader(cfd) + >>> for row in reader: + >>> # convert each row to a numpy array + >>> array = np.array([int(x) for x in row], np.int64) + >>> # write the array to the output file handle + >>> fd.write(array.tobytes()) Compression =========== From 1d77827f25f747818b1fa48e2f616d219dce8fe0 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 15:38:39 -0500 Subject: [PATCH 03/10] set sphinx-asdf pin --- asdf/schema.py | 2 +- docs/conf.py | 70 +++++++++++++++++++++++++++++++++++++++++++------- pyproject.toml | 3 ++- 3 files changed, 64 insertions(+), 11 deletions(-) diff --git a/asdf/schema.py b/asdf/schema.py index 5fd6d5278..683023c23 100644 --- a/asdf/schema.py +++ b/asdf/schema.py @@ -575,7 +575,7 @@ def validate(instance, ctx=None, schema=None, validators=None, reading=False, *a tag on the instance. The additional ``*args`` and ``**kwargs`` are passed along to - `~jsonschema.protocols.Validator.validate`. + the validator. Parameters ---------- diff --git a/docs/conf.py b/docs/conf.py index 5cf496b93..38e5e266a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,8 +7,6 @@ else: import tomllib -from sphinx_asdf.conf import * # noqa: F403 - # The standard library importlib.metadata returns duplicate entrypoints # for all python versions up to and including 3.11 # https://github.com/python/importlib_metadata/issues/410#issuecomment-1304258228 @@ -59,10 +57,16 @@ ] # Add intersphinx mappings -intersphinx_mapping["semantic_version"] = ("https://python-semanticversion.readthedocs.io/en/latest/", None) -intersphinx_mapping["jsonschema"] = ("https://python-jsonschema.readthedocs.io/en/stable/", None) -intersphinx_mapping["stdatamodels"] = ("https://stdatamodels.readthedocs.io/en/latest/", None) -intersphinx_mapping["pytest"] = ("https://docs.pytest.org/en/latest/", None) +intersphinx_mapping = { + #"jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "pypa-packaging": ("https://packaging.python.org/en/latest/", None), + "pytest": ("https://docs.pytest.org/en/latest/", None), + "python": ("https://docs.python.org/3/", None), + "semantic_version": ("https://python-semanticversion.readthedocs.io/en/latest/", None), + "stdatamodels": ("https://stdatamodels.readthedocs.io/en/latest/", None), +} + # Docs are hosted as a "subproject" under the main project's domain: https://www.asdf-format.org/projects # This requires including links to main project (asdf-website) and the other asdf subprojects @@ -77,19 +81,67 @@ "asdf-wcs-schemas": ("https://www.asdf-format.org/projects/asdf-wcs-schemas/en/latest/", None), } -intersphinx_mapping.update(subprojects) # noqa: F405 -extensions += ["sphinx_inline_tabs", "sphinx.ext.intersphinx", "sphinx.ext.extlinks"] # noqa: F405 +intersphinx_mapping.update(subprojects) + +extensions = [ + "sphinx_inline_tabs", + "sphinx.ext.intersphinx", + "sphinx.ext.extlinks", + "sphinx_asdf", + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinxcontrib.jquery', + 'numpydoc', + 'pytest_doctestplus.sphinx.doctestplus', + #'sphinx_astropy.ext.changelog_links', + #'sphinx_astropy.ext.generate_config', + #'sphinx_astropy.ext.intersphinx_toggle', + #'sphinx_astropy.ext.missing_static', + 'sphinx_automodapi.automodapi', + 'sphinx_automodapi.smart_resolver', +] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The reST default role (used for this markup: `text`) to use for all +# documents. Set to the "smart" one. +default_role = 'obj' + +# Don't show summaries of the members in each class along with the +# class' docstring +numpydoc_show_class_members = False + +autosummary_generate = True + +automodapi_toctreedirnm = 'api' + +# Class documentation should contain *both* the class docstring and +# the __init__ docstring +autoclass_content = "both" html_theme = "furo" html_static_path = ["_static"] -# Override default settings from sphinx_asdf / sphinx_astropy (incompatible with furo) html_sidebars = {} # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. html_favicon = "_static/images/favicon.ico" html_logo = "" +html_last_updated_fmt = '%d %b %Y' globalnavlinks = { "ASDF Projects": "https://www.asdf-format.org", diff --git a/pyproject.toml b/pyproject.toml index 62c6ceaa5..5c0ec8312 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,7 +38,8 @@ http = [ "fsspec[http]>=2022.8.2", ] docs = [ - "sphinx-asdf>=0.2.2", + #"sphinx-asdf>=0.2.2", + "sphinx-asdf @ git+https://github.com/braingram/sphinx-asdf@remove_theme", "graphviz", "sphinx-inline-tabs", 'tomli; python_version < "3.11"', From cec7eae6d80947bacc2003d268238eae360f13a0 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 15:40:14 -0500 Subject: [PATCH 04/10] fix style --- docs/conf.py | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 38e5e266a..c6e890f0e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -58,7 +58,7 @@ # Add intersphinx mappings intersphinx_mapping = { - #"jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable/", None), + # "jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable/", None), "numpy": ("https://numpy.org/doc/stable/", None), "pypa-packaging": ("https://packaging.python.org/en/latest/", None), "pytest": ("https://docs.pytest.org/en/latest/", None), @@ -89,37 +89,37 @@ "sphinx.ext.intersphinx", "sphinx.ext.extlinks", "sphinx_asdf", - 'sphinx.ext.autodoc', - 'sphinx.ext.coverage', - 'sphinx.ext.inheritance_diagram', - 'sphinx.ext.intersphinx', - 'sphinx.ext.mathjax', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'sphinxcontrib.jquery', - 'numpydoc', - 'pytest_doctestplus.sphinx.doctestplus', + "sphinx.ext.autodoc", + "sphinx.ext.coverage", + "sphinx.ext.inheritance_diagram", + "sphinx.ext.intersphinx", + "sphinx.ext.mathjax", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinxcontrib.jquery", + "numpydoc", + "pytest_doctestplus.sphinx.doctestplus", #'sphinx_astropy.ext.changelog_links', #'sphinx_astropy.ext.generate_config', #'sphinx_astropy.ext.intersphinx_toggle', #'sphinx_astropy.ext.missing_static', - 'sphinx_automodapi.automodapi', - 'sphinx_automodapi.smart_resolver', + "sphinx_automodapi.automodapi", + "sphinx_automodapi.smart_resolver", ] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] +exclude_patterns = ["_build"] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # The master toctree document. -master_doc = 'index' +master_doc = "index" # The reST default role (used for this markup: `text`) to use for all # documents. Set to the "smart" one. -default_role = 'obj' +default_role = "obj" # Don't show summaries of the members in each class along with the # class' docstring @@ -127,7 +127,7 @@ autosummary_generate = True -automodapi_toctreedirnm = 'api' +automodapi_toctreedirnm = "api" # Class documentation should contain *both* the class docstring and # the __init__ docstring @@ -141,7 +141,7 @@ # pixels large. html_favicon = "_static/images/favicon.ico" html_logo = "" -html_last_updated_fmt = '%d %b %Y' +html_last_updated_fmt = "%d %b %Y" globalnavlinks = { "ASDF Projects": "https://www.asdf-format.org", From 0904f72ecc6e74efaed9bf89bddfb45fa45c85df Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 16:57:22 -0500 Subject: [PATCH 05/10] fix array docs example --- docs/asdf/arrays.rst | 6 +++--- docs/conf.py | 1 + pyproject.toml | 3 +-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/asdf/arrays.rst b/docs/asdf/arrays.rst index 4ae60f44c..92181752b 100644 --- a/docs/asdf/arrays.rst +++ b/docs/asdf/arrays.rst @@ -217,9 +217,9 @@ to numpy arrays stored in ASDF: >>> from asdf.tags.core import Stream >>> tree = { - >>> # We happen to know in advance that each row in the CSV has 100 ints - >>> 'data': Stream([100], np.int64) - >>> } + ... # We happen to know in advance that each row in the CSV has 100 ints + ... 'data': Stream([100], np.int64) + ... } >>> ff = AsdfFile(tree) >>> # open the output file handle diff --git a/docs/conf.py b/docs/conf.py index c6e890f0e..d0e5d9b5b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,6 +85,7 @@ intersphinx_mapping.update(subprojects) extensions = [ + # TODO clean these up, do we need them all? "sphinx_inline_tabs", "sphinx.ext.intersphinx", "sphinx.ext.extlinks", diff --git a/pyproject.toml b/pyproject.toml index 5c0ec8312..62c6ceaa5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,8 +38,7 @@ http = [ "fsspec[http]>=2022.8.2", ] docs = [ - #"sphinx-asdf>=0.2.2", - "sphinx-asdf @ git+https://github.com/braingram/sphinx-asdf@remove_theme", + "sphinx-asdf>=0.2.2", "graphviz", "sphinx-inline-tabs", 'tomli; python_version < "3.11"', From 5701a0c27e6b16978477eff0c05b6097eb9da0a5 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 17:04:14 -0500 Subject: [PATCH 06/10] attempt to fix what should be a skipped doctest --- docs/asdf/arrays.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/asdf/arrays.rst b/docs/asdf/arrays.rst index 92181752b..fe3924fde 100644 --- a/docs/asdf/arrays.rst +++ b/docs/asdf/arrays.rst @@ -224,16 +224,16 @@ to numpy arrays stored in ASDF: >>> ff = AsdfFile(tree) >>> # open the output file handle >>> with open('new_file.asdf', 'wb') as fd: - >>> ff.write_to(fd) - >>> # open the CSV file to be converted - >>> with open('large_file.csv', 'r') as cfd: - >>> # read each line of the CSV file - >>> reader = csv.reader(cfd) - >>> for row in reader: - >>> # convert each row to a numpy array - >>> array = np.array([int(x) for x in row], np.int64) - >>> # write the array to the output file handle - >>> fd.write(array.tobytes()) + ... ff.write_to(fd) + ... # open the CSV file to be converted + ... with open('large_file.csv', 'r') as cfd: + ... # read each line of the CSV file + ... reader = csv.reader(cfd) + ... for row in reader: + ... # convert each row to a numpy array + ... array = np.array([int(x) for x in row], np.int64) + ... # write the array to the output file handle + ... fd.write(array.tobytes()) Compression =========== From 3cdf72b18ed6ee69ba3a926027d56f4bf7ba7ea9 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 17:07:49 -0500 Subject: [PATCH 07/10] switch to a code block --- docs/asdf/arrays.rst | 50 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/asdf/arrays.rst b/docs/asdf/arrays.rst index fe3924fde..07ab3a189 100644 --- a/docs/asdf/arrays.rst +++ b/docs/asdf/arrays.rst @@ -209,31 +209,31 @@ of the data in memory as an intermediate step. Consider the following example that streams a large CSV file containing rows of integer data and converts it to numpy arrays stored in ASDF: -.. doctest-skip:: - - >>> import csv - >>> import numpy as np - >>> from asdf import AsdfFile - >>> from asdf.tags.core import Stream - - >>> tree = { - ... # We happen to know in advance that each row in the CSV has 100 ints - ... 'data': Stream([100], np.int64) - ... } - - >>> ff = AsdfFile(tree) - >>> # open the output file handle - >>> with open('new_file.asdf', 'wb') as fd: - ... ff.write_to(fd) - ... # open the CSV file to be converted - ... with open('large_file.csv', 'r') as cfd: - ... # read each line of the CSV file - ... reader = csv.reader(cfd) - ... for row in reader: - ... # convert each row to a numpy array - ... array = np.array([int(x) for x in row], np.int64) - ... # write the array to the output file handle - ... fd.write(array.tobytes()) +.. code:: + + import csv + import numpy as np + from asdf import AsdfFile + from asdf.tags.core import Stream + + tree = { + # We happen to know in advance that each row in the CSV has 100 ints + 'data': Stream([100], np.int64) + } + + ff = AsdfFile(tree) + # open the output file handle + with open('new_file.asdf', 'wb') as fd: + ff.write_to(fd) + # open the CSV file to be converted + with open('large_file.csv', 'r') as cfd: + # read each line of the CSV file + reader = csv.reader(cfd) + for row in reader: + # convert each row to a numpy array + array = np.array([int(x) for x in row], np.int64) + # write the array to the output file handle + fd.write(array.tobytes()) Compression =========== From 67e55217139bdf8516ac1d4237079fd57d52a61e Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 16 Jan 2026 17:14:42 -0500 Subject: [PATCH 08/10] remove unused pytest-doctestplus --- docs/conf.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d0e5d9b5b..6efe1ef88 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -99,11 +99,6 @@ "sphinx.ext.viewcode", "sphinxcontrib.jquery", "numpydoc", - "pytest_doctestplus.sphinx.doctestplus", - #'sphinx_astropy.ext.changelog_links', - #'sphinx_astropy.ext.generate_config', - #'sphinx_astropy.ext.intersphinx_toggle', - #'sphinx_astropy.ext.missing_static', "sphinx_automodapi.automodapi", "sphinx_automodapi.smart_resolver", ] From 116d917f6234e7c089b2599b4df17e014e79964b Mon Sep 17 00:00:00 2001 From: Brett Date: Tue, 20 Jan 2026 08:17:26 -0500 Subject: [PATCH 09/10] remove comment --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 6efe1ef88..0537845bc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -58,7 +58,6 @@ # Add intersphinx mappings intersphinx_mapping = { - # "jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable/", None), "numpy": ("https://numpy.org/doc/stable/", None), "pypa-packaging": ("https://packaging.python.org/en/latest/", None), "pytest": ("https://docs.pytest.org/en/latest/", None), From ab89f93cf7f6920718e9934c8a6d413b7cf14357 Mon Sep 17 00:00:00 2001 From: Brett Date: Tue, 20 Jan 2026 08:46:07 -0500 Subject: [PATCH 10/10] remove defaults channel --- docs/rtd_environment.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/rtd_environment.yaml b/docs/rtd_environment.yaml index bacbf8484..f4194e813 100644 --- a/docs/rtd_environment.yaml +++ b/docs/rtd_environment.yaml @@ -1,7 +1,6 @@ name: rtd311 channels: - conda-forge - - defaults dependencies: - python=3.13 - pip