Refactor ASDF docs

.github/workflows/ci.yml

@@ -57,6 +57,11 @@ jobs:
             python-version: "3.9"
             toxenv: codestyle
 
+          - name: Build Documents
+            python-version: "3.9"
+            os: ubuntu-latest
+            toxenv: docbuild
+
           - name: Twine
             os: ubuntu-latest
             python-version: "3.9"
@@ -77,7 +82,6 @@ jobs:
             python-version: "3.9"
             toxenv: py39-gwcsdev
 
-          # Fail
           - name: Numpy Dev
             os: ubuntu-latest
             python-version: "3.9"
@@ -103,7 +107,6 @@ jobs:
             python-version: "3.9"
             toxenv: py39-asdfcoordinatesschemasdev
 
-          # Fail
           - name: Pre-Release Dependencies
             os: ubuntu-latest
             python-version: "3.9"

.readthedocs.yml

@@ -2,6 +2,8 @@ version: 2
 
 build:
   os: ubuntu-20.04
+  apt_packages:
+    - graphviz
   tools:
     python: "3.9"
 

CHANGES.rst

@@ -1,47 +1,70 @@
+2.12.1 (unreleased)
+-------------------
+
+The ASDF Standard is at v1.6.0
+
+- Overhaul of the ASDF documentation to make it more consistent and readable. [#1142]
+
 2.12.0 (2022-06-06)
 -------------------
 
+The ASDF Standard is at v1.6.0
+
 - Added ability to display title as a comment in using the
   ``info()`` functionality. [#1138]
 - Add ability to set asdf-standard version for schema example items. [#1143]
 
 2.11.1 (2022-04-15)
 -------------------
 
+The ASDF Standard is at v1.6.0
+
 - Update minimum astropy version to 5.0.4. [#1133]
 
 2.11.0 (2022-03-15)
 -------------------
 
+The ASDF Standard is at v1.6.0
+
 - Update minimum jsonschema version to 4.0.1. [#1105]
 
 2.10.1 (2022-03-02)
 -------------------
 
+The ASDF Standard is at v1.6.0
+
 - Bugfix for circular build dependency for asdf. [#1094]
 
 - Fix small bug with handling multiple schema uris per tag. [#1095]
 
 2.10.0 (2022-02-17)
 -------------------
 
+The ASDF Standard is at v1.6.0
+
 - Replace asdf-standard submodule with pypi package. [#1079]
 
 2.9.2 (2022-02-07)
 ------------------
 
+The ASDF Standard is at v1.6.0
+
 - Fix deprecation warnings stemming from the release of pytest 7.0.0. [#1075]
 
 - Fix bug in pytest plugin when schemas are not in a directory named "schemas". [#1076]
 
 2.9.1 (2022-02-03)
 ------------------
 
+The ASDF Standard is at v1.6.0
+
 - Fix typo in testing module ``__init__.py`` name. [#1071]
 
 2.9.0 (2022-02-02)
 ------------------
 
+The ASDF Standard is at v1.6.0
+
 - Added the capability for tag classes to provide an interface
   to asdf info functionality to obtain information about the
   class attributes rather than appear as an opaque class object.
@@ -67,11 +90,15 @@
 2.8.3 (2021-12-13)
 ------------------
 
+The ASDF Standard is at v1.6.0
+
 - Fix more use of 'python' where 'python3' is intended. [#1033]
 
 2.8.2 (2021-12-06)
 ------------------
 
+The ASDF Standard is at v1.6.0
+
 - Update documentation to reflect new 2.8 features. [#998]
 
 - Fix array compression for non-native byte order [#1010]
@@ -93,6 +120,8 @@
 2.8.0 (2021-05-12)
 ------------------
 
+The ASDF Standard is at v1.6.0
+
 - Add ``yaml_tag_handles`` property to allow definition of custom yaml
   ``%TAG`` handles in the asdf file header. [#963]
 
@@ -170,6 +199,8 @@
 2.7.5 (2021-06-09)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - Fix bug in ``asdf.schema.check_schema`` causing relative references in
   metaschemas to be resolved incorrectly. [#987]
 
@@ -179,6 +210,8 @@
 2.7.4 (2021-04-30)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - Fix pytest plugin failure under older versions of pytest. [#934]
 
 - Copy array views when the base array is non-contiguous. [#949]
@@ -192,6 +225,8 @@
 2.7.3 (2021-02-25)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - Add pytest plugin options to skip and xfail individual tests
   and xfail the unsupported ndarray-1.0.0 example. [#929]
 
@@ -201,19 +236,25 @@
 2.7.2 (2021-01-15)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - Fix bug causing test collection failures in some environments. [#889]
 
 - Fix bug when decompressing arrays with numpy 1.20.  [#901, #909]
 
 2.7.1 (2020-08-18)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - Fix bug preventing access to copied array data after
   ``AsdfFile`` is closed. [#869]
 
 2.7.0 (2020-07-23)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - Fix bug preventing diff of files containing ndarray-1.0.0
   objects in simplified form. [#786]
 
@@ -274,6 +315,8 @@
 2.6.0 (2020-04-22)
 ------------------
 
+The ASDF Standard is at v1.5.0
+
 - AsdfDeprecationWarning now subclasses DeprecationWarning. [#710]
 
 - Resolve external references in custom schemas, and deprecate
@@ -307,6 +350,8 @@
 2.5.2 (2020-02-28)
 ------------------
 
+The ASDF Standard is at v1.4.0
+
 - Add a developer overview document to help understand how ASDF works
   internally. Still a work in progress. [#730]
 
@@ -324,12 +369,16 @@
 2.5.1 (2020-01-07)
 ------------------
 
+The ASDF Standard is at v1.4.0
+
 - Fix bug in test causing failure when test suite is run against
   an installed asdf package. [#732]
 
 2.5.0 (2019-12-23)
 ------------------
 
+The ASDF Standard is at v1.4.0
+
 - Added asdf-standard 1.4.0 to the list of supported versions. [#704]
 - Fix load_schema LRU cache memory usage issue [#682]
 - Add convenience method for fetching the default resolver [#682]
@@ -344,12 +393,16 @@
 2.4.2 (2019-08-29)
 ------------------
 
+The ASDF Standard is at v1.3.0
+
 - Limit the version of ``semantic_version`` to <=2.6.0 to work
   around a Deprecation warning. [#700]
 
 2.4.1 (2019-08-27)
 ------------------
 
+The ASDF Standard is at v1.3.0
+
 - Define the ``in`` operator for top-level ``AsdfFile`` objects. [#623]
 
 - Overhaul packaging infrastructure. Remove use of ``astropy_helpers``. [#670]
@@ -363,15 +416,14 @@
 
 - Add support for jsonschema 3.x. [#684]
 
-2.3.4 (unreleased)
-------------------
-
 - Fix bug in ``NDArrayType.__len__``.  It must be a method, not a
   property. [#673]
 
 2.3.3 (2019-04-02)
 ------------------
 
+The ASDF Standard is at v1.3.0
+
 - Pass ``ignore_unrecognized_tag`` setting through to ASDF-in-FITS. [#650]
 
 - Use ``$schema`` keyword if available to determine meta-schema to use when
@@ -387,12 +439,16 @@
 2.3.2 (2019-02-19)
 ------------------
 
+The ASDF Standard is at v1.3.0
+
 - Fix bug that occurs when comparing installed extension version with that
   found in file. [#641]
 
 2.3.1 (2018-12-20)
 ------------------
 
+The ASDF Standard is at v1.3.0
+
 - Provide source information for ``AsdfDeprecationWarning`` that come from
   extensions from external packages. [#629]
 
@@ -407,6 +463,8 @@
 2.3.0 (2018-11-28)
 ------------------
 
+The ASDF Standard is at v1.3.0
+
 - Storage of arbitrary precision integers is now provided by
   ``asdf.IntegerType``.  Reading a file with integer literals that are too
   large now causes only a warning instead of a validation error. This is to

README.rst

@@ -19,6 +19,9 @@ ASDF - Advanced Scientific Data Format
 .. image:: https://codecov.io/gh/asdf-format/asdf/branch/master/graphs/badge.svg
     :target: https://codecov.io/gh/asdf-format/asdf
 
+.. image:: https://zenodo.org/badge/18112754.svg
+    :target: https://zenodo.org/badge/latestdoi/18112754
+
 .. image:: https://img.shields.io/pypi/l/asdf.svg
     :target: https://img.shields.io/pypi/l/asdf.svg
 
@@ -101,10 +104,12 @@ input to the constructor of `AsdfFile`:
     # Write the data to a new file
     af.write_to('example.asdf')
 
-If we open the newly created file, we can see some of the key features
+If we open the newly created file's metadata section, we can see some of the key features
 of ASDF on display:
 
-::
+.. _begin-example-asdf-metadata:
+
+.. code:: yaml
 
     #ASDF 1.0.0
     #ASDF_STANDARD 1.2.0
@@ -138,11 +143,16 @@ of ASDF on display:
       shape: [100]
     ...
 
+.. _end-example-asdf-metadata:
+
 The metadata in the file mirrors the structure of the tree that was stored. It
 is hierarchical and human-readable. Notice that metadata has been added to the
 tree that was not explicitly given by the user. Notice also that the numerical
 array data is not stored in the metadata tree itself. Instead, it is stored as
-binary data blocks below the metadata section (not shown here).
+binary data blocks below the metadata section (not shown above).
+
+.. _end-create-file-text:
+.. _begin-compress-file:
 
 It is possible to compress the array data when writing the file:
 
@@ -154,7 +164,7 @@ The built-in compression algorithms are ``'zlib'``, and ``'bzp2'``.  The
 ``'lz4'`` algorithm becomes available when the `lz4 <https://python-lz4.readthedocs.io/>`__ package
 is installed.  Other compression algorithms may be available via extensions.
 
-.. _end-create-file-text:
+.. _end-compress-file:
 
 Reading a file
 ~~~~~~~~~~~~~~

asdf/resource.py

@@ -5,7 +5,7 @@
 import pkgutil
 from collections.abc import Mapping
 
-from asdf_standard import DirectoryResourceMapping
+from asdf_standard import DirectoryResourceMapping as _DirectoryResourceMapping
 
 from .util import get_class_name
 
@@ -18,6 +18,16 @@
 ]
 
 
+class DirectoryResourceMapping(_DirectoryResourceMapping):
+    """
+    A resource mapping that reads resource content from a directory or directory tree.
+
+    See :class:`~asdf_standard.resource.DirectoryResourceMapping` for details.
+    """
+
+    pass
+
+
 class ResourceMappingProxy(Mapping):
     """
     Wrapper around a resource mapping that carries