docs/asdf-website-changes

.gitignore

@@ -132,3 +132,6 @@ dmypy.json
 
 # Ignore generated Sphinx documentation
 docs/source/generated/
+
+# Mac OS
+.DS_STORE

CHANGES.rst

@@ -3,6 +3,7 @@
 
 - Update reference files [#409]
 - Remove statement discouraging use of YAML anchors and aliases [#443]
+- Documentation config changes in preparation for ASDF website [#446]
 
 1.1.1 (2024-03-06)
 ------------------

docs/Makefile

@@ -22,3 +22,7 @@ clean:
 	-rm -rf $(BUILDDIR)
 	-rm -rf source/api
 	-rm -rf source/generated
+
+.PHONY: livehtml
+livehtml: ## Serve documentation on localhost:8000, with live-reload
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/_static/custom.css → docs/source/_static/css/custom.css

@@ -41,3 +41,8 @@ div.highlight-python {
 div.highlight-python:active {
     width: 150%
 }
+
+object.graphviz {
+    max-width: 100%;
+    background-color: white;
+}

docs/source/asdf-schemas.rst

@@ -0,0 +1,63 @@
+.. _asdf-schemas:
+
+ASDF Schemas
+============
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   Schema Definitions <definitions.rst>
+   Meta Schemas <meta-schemas.rst>
+   Manifests <manifest.rst>
+   Schema Implementation <implementation.rst>
+   Schema Design and Editing <extending-asdf.rst>
+   Default Annotation <default-annotation.rst>
+
+
+ASDF uses `JSON Schema`_ to perform validation of ASDF files. Schema validation
+of ASDF files serves the following purposes:
+
+* Ensures conformity with core data types defined by the ASDF Standard. ASDF
+  readers can detect whether an ASDF file has been modified in a way that would
+  render it unreadable or unrecognizable.
+* Enables interoperability between ASDF implementations. Implementations that
+  recognize the same schema definitions should be able to interpret files
+  containing instances of data types that conform to those schemas.
+* Allows for the definition of custom data types. External software packages
+  can provide ASDF schemas that correspond to types provided by that package,
+  and then serialize instances of those types in a way that is standardized
+  and portable.
+
+All ASDF implementations must implement the types defined by the `core schemas
+<core-schema>` and validate against them when reading files. [#]_
+
+.. note::
+  .. [#]
+
+  Implementations may expose the control of validation on reading to the
+  user (e.g. to disable it on demand). However, validation on reading should
+  be the default behavior.
+
+
+The ASDF
+Standard also defines other schemas, which are optional for ASDF implementations
+and maintained as part of the standard (mainly for historical reasons):
+
+* :ref:`astronomy <astronomy-schema>`
+
+More information on the schemas defined by ASDF can be found in :ref:`schema`.
+
+The ASDF Standard also defines two metaschemas which are used to validate the
+ASDF schemas themselves:
+
+* :doc:`YAML schema <yaml_schema>`
+* :doc:`ASDF Schema <asdf>`
+
+The ASDF tags (described by schemas) available under each ASDF standard version are all described
+by a single :doc:`manifest <manifest>` document for that ASDF standard version.
+
+
+.. Links
+
+.. _JSON Schema: http://json-schema.org

docs/source/asdf.rst

@@ -0,0 +1,13 @@
+.. _asdf:
+
+ASDF Schema
+===========
+
+.. _asdf-schema-1.1.0:
+
+
+.. asdf-schema::
+   :schema_root: ../../resources/schemas/stsci.edu
+   :standard_prefix:
+
+   asdf/asdf-schema-1.1.0

docs/source/conf.py

@@ -4,13 +4,14 @@
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
-
 import datetime
 import importlib.metadata
+import os
 from pathlib import Path
 
 import tomli
 from sphinx_asdf.conf import *  # noqa: F403
+from sphinx_asdf.conf import extensions, intersphinx_mapping
 
 # -- Project information -----------------------------------------------------
 
@@ -21,7 +22,7 @@
 
 project = configuration["name"]
 author = f"{configuration['authors'][0]['name']} <{configuration['authors'][0]['email']}>"
-copyright = f"{datetime.datetime.now().year}, {configuration['authors'][0]}"
+copyright = f"{datetime.datetime.now().year}, {author}"
 
 # The short X.Y version
 with open(Path(__file__).parent.parent.parent / "README.md") as readme:
@@ -30,14 +31,33 @@
 # The full version, including alpha/beta/rc tags
 release = importlib.metadata.version(configuration["name"])
 
-intersphinx_mapping["asdf"] = ("https://asdf.readthedocs.io/en/latest/", None)  # noqa: F405
+subproject_mappings = {
+    # Main project
+    "asdf-website": ("https://www.asdf-format.org/en/latest/", None),
+    # Subprojects
+    "asdf": ("https://asdf.readthedocs.io/en/latest/", None),
+    "asdf-coordinates-schemas": ("https://www.asdf-format.org/projects/asdf-coordinates-schemas/en/latest/", None),
+    "asdf-transform-schemas": ("https://www.asdf-format.org/projects/asdf-transform-schemas/en/latest/", None),
+    "asdf-wcs-schemas": ("https://www.asdf-format.org/projects/asdf-wcs-schemas/en/latest/", None),
+}
+intersphinx_mapping.update(subproject_mappings)  # noqa: F405
+
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions += ["sphinx.ext.mathjax", "sphinx.ext.ifconfig", "sphinx.ext.graphviz", "sphinx_asdf"]  # noqa: F405
+
+extensions += [
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
+    "sphinx_asdf",
+]  # noqa: F405
+
 
 mathjax_path = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 
@@ -50,9 +70,6 @@
 # source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
-# The root toctree document.
-root_doc = "index"
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -61,7 +78,10 @@
 language = "en"
 
 # The name of the Pygments (syntax highlighting) style to use.
-# pygments_style = "sphinx"
+pygments_style = "monokai"
+
+# NB Dark style pygments is furo-specific at this time
+pygments_dark_style = "monokai"
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 default_role = "ref"
@@ -75,32 +95,46 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "sphinx_rtd_theme"
-
-# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+html_title = "ASDF Standard"
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-html_theme_options = {}
+# Override default settings from sphinx_asdf / sphinx_astropy (incompatible with furo)
+html_sidebars = {}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+static_dir = os.path.join(os.path.dirname(__file__), "_static")
+
+# The root toctree document.
+root_doc = "index"
+
+master_doc = "index"
+
+# The theme to use for HTML and HTML Help pages.
+
+html_theme = "furo"
+
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+html_theme_path = []
+
+html_additional_pages = {}
 
 # 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/logo.ico"
-html_logo = "_static/logo.png"
+html_favicon = "_static/images/favicon.ico"
+html_logo = ""
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    "light_logo": "images/logo-light-mode.png",
+    "dark_logo": "images/logo-dark-mode.png",
+}
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -125,8 +159,20 @@
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 html_show_copyright = True
 
-html_context = {"bootswatch_css_custom": ["_static/asdfstandard.css"]}
+# html_context = {"bootswatch_css_custom": ["_static/custom.css"]}
+
+# Render inheritance diagrams in SVG
+graphviz_output_format = "svg"
 
+graphviz_dot_args = [
+    "-Nfontsize=10",
+    "-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+    "-Efontsize=10",
+    "-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+    "-Gbgcolor=white",
+    "-Gfontsize=10",
+    "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+]
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -182,7 +228,7 @@
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-latex_logo = "_static/logo.pdf"
+latex_logo = "_static/images/logo-light.png"
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.

docs/source/schemas/core.rst → docs/source/core.rst

@@ -6,6 +6,10 @@ Core
 The ``core`` module contains schema that must be implemented by every
 asdf library.
 
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
 .. asdf-autoschemas::
 
    core/asdf-1.1.0

docs/source/default-annotation.rst

@@ -0,0 +1,31 @@
+.. _default-annotation:
+
+Default annotation
+==================
+
+The JSON Schema spec includes a schema annotation attribute called ``default`` that
+can be used to describe the default value of a data attribute when that attribute
+is missing.  Recent versions of the spec `point out <http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.7.7.1.1>`__
+that there is no single correct way to choose an annotation value when multiple
+are available due to references and combiners.  This presents a problem when
+trying to fill in missing data in a file based on the schema ``default``: if
+multiple conflicting values are available, the software does not know how to choose.
+
+Previous versions of the ASDF Standard did not offer guidance on how
+to use ``default``.  The Python reference implementation read the first default
+that it encountered as a literal value and inserted that value into the tree when
+the corresponding attribute was otherwise missing.  Until version 2.8, it also
+removed attributes on write whose values matched their schema defaults.  The
+resulting files would appear to the casual viewer to be missing data, and may in
+fact be invalid against their schemas if the any of the removed attributes were required.
+
+Implementations **must not** remove attributes with default values from the tree.
+Beginning with ASDF Standard 1.6.0, implementations also must not fill default values
+directly from the schema.  This will avoid ambiguity when multiple schema defaults
+are present, and also permit the ``default`` attribute to contain a description
+that is not appropriate to use as a literal default value.  For example::
+
+    default: An array of zeros matching the dimensions of the data array.
+
+For ASDF Standard < 1.6.0, filling default values from the schema is required.  This is
+necessary to support files written by older versions of the Python implementation.

docs/source/definitions.rst

@@ -0,0 +1,14 @@
+.. _schema:
+
+Schema Definitions
+==================
+
+ASDF schemas are arranged into "modules".  All ASDF implementations
+must support the "core" module, but the other modules are optional.
+
+.. toctree::
+   :maxdepth: 2
+
+   core <core.rst>
+   astronomy <astronomy.rst>
+   legacy <legacy.rst>