docs: Usage examples

.gitignore

@@ -1 +1,2 @@
 Manifest*.toml
+data/

docs/Project.toml

@@ -1,9 +1,9 @@
 [deps]
 ASDF = "686f71d1-807d-59a4-a860-28280ea06d7b"
+AWS = "fbe9abb3-538b-5e4e-ba9e-bc94f4f92ebc"
+AWSS3 = "1c724243-ef5b-51ab-93f4-b0a88ac62a95"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 
 [compat]
 Documenter = "1"
-
-[source]
-ASDF = {path = ".."}

docs/make.jl

@@ -1,8 +1,3 @@
-# Generate documentation with this command:
-# (cd docs && julia make.jl)
-
-push!(LOAD_PATH, "..")
-
 using ASDF
 using Documenter
 using Documenter.Remotes: GitHub
@@ -13,9 +8,17 @@ makedocs(;
     repo = GitHub("JuliaAstro/ASDF.jl"),
     sitename = "ASDF.jl",
     format = Documenter.HTML(
-        prettyurls = true,
         canonical = "https://juliaastro.org/ASDF/stable/",
     ),
+    pages = [
+        "Home" => "index.md",
+        "Introduction" => "intro.md",
+        "Examples" => [
+            "JWST" => "examples/jwst.md",
+            "Roman" => "examples/roman.md",
+    ],
+        "API" => "api.md",
+    ],
 )
 
 deploydocs(;

docs/src/api.md

@@ -0,0 +1,5 @@
+# API
+
+```@autodocs
+Modules = [ASDF]
+```

docs/src/examples/jwst.md

@@ -0,0 +1,38 @@
+# JWST
+
+*Adapted from [ADASS 2024 workshop](https://github.com/asdf-format/asdf-adass2024/blob/main/02_working_with_asdf/Working_with_ASDF.ipynb).*
+
+## Reading an ASDF file
+
+```@example jwst
+using ASDF
+
+af = ASDF.load_file("../../data/jwst.asdf")
+
+af.metadata
+```
+
+```@example jwst
+img_sci = let
+    img = af.metadata["data"][]
+    img[img .< 0] .= 1
+    img
+end
+```
+
+And plot:
+
+```@example jwst
+using CairoMakie
+
+fig, ax, hm = heatmap(img_sci;
+    colorrange = (1, 1e3),
+    colorscale = log10,
+    colormap = :cividis,
+    nan_color = :lime, # NaNs are handled automatically
+)
+
+Colorbar(fig[1, 2], hm)
+
+fig
+```

docs/src/examples/roman.md

@@ -0,0 +1 @@
+# Roman

docs/src/index.md

@@ -1,5 +1,25 @@
 # ASDF.jl
 
-```@autodocs
-Modules = [ASDF]
+A new [Advanced Scientific Data Format (ASDF)](https://asdf-standard.readthedocs.io/en/latest/index.html) package, written in Julia.
+
+
+## Quickstart
+
+```julia
+using ASDF
+```
+
+```julia
+# Load
+af = ASDF.load_file("<file.asdf>")
+```
+
+```julia
+# Modify
+af.metadata["<key>"] = <val>
+```
+
+```julia
+# Write
+ASDF.write_file("<new_file.asdf>")
 ```

docs/src/intro.md

@@ -0,0 +1,44 @@
+# Introduction
+
+*Adapted from [ADASS 2024 workshop](https://github.com/asdf-format/asdf-adass2024/blob/main/03_creating_asdf_files/Creating_ASDF_Files.ipynb).*
+
+## Getting started
+
+Created via a regular dictionary:
+
+```@example intro
+af_payload = Dict{Any, Any}( # To-do: see if type signature needs to be this general
+    "meta" => Dict("my" => Dict("nested" => "metadata")),
+    "data" => [1, 2, 3, 4],
+)
+```
+
+Write and load with `ASDF.write_file` and `ASDF.load_file`, respectively:
+
+```@example intro
+using ASDF
+
+ASDF.write_file("../data/my_asdf.asdf", af_payload)
+
+af = ASDF.load_file("../data/my_asdf.asdf")
+```
+
+This contains a `meta` field, which is a dictionary that merges information about this library with `af_payload`:
+
+```@example intro
+af.metadata
+```
+
+```@example intro
+af.metadata["asdf/library"]
+```
+
+## Tagged objects
+
+Supporting custom objects, extensions.
+
+## Array storage
+
+```julia
+ASDF.NDArrayWrapper(...; inline, compression)
+```

src/ASDF.jl

@@ -511,9 +511,27 @@ end
 
 ################################################################################
 
+# ASDF
 asdf_constructors = copy(YAML.default_yaml_constructors)
 asdf_constructors["tag:stsci.edu:asdf/core/asdf-1.1.0"] = asdf_constructors["tag:yaml.org,2002:map"]
 asdf_constructors["tag:stsci.edu:asdf/core/software-1.0.0"] = asdf_constructors["tag:yaml.org,2002:map"]
+asdf_constructors["tag:stsci.edu:asdf/core/extension_metadata-1.0.0"] = asdf_constructors["tag:yaml.org,2002:map"]
+asdf_constructors["tag:stsci.edu:asdf/unit/unit-1.0.0"] = asdf_constructors["tag:yaml.org,2002:str"]
+
+# In load_file, pass multi_constructors as the second dict argument:
+multi_constructors = Dict{String, Function}()
+
+# ASDF transforms
+multi_constructors["tag:stsci.edu:asdf/transform/"] = (constructor, tag_suffix, node) ->
+    YAML.construct_mapping(constructor, node)
+
+# GWCS
+multi_constructors["tag:stsci.edu:gwcs/"] = (constructor, tag_suffix, node) ->
+    YAML.construct_mapping(constructor, node)
+
+# Astropy
+multi_constructors["tag:astropy.org:astropy/"] = (constructor, tag_suffix, node) ->
+    YAML.construct_mapping(constructor, node)
 
 function load_file(filename::AbstractString)
     io = open(filename, "r")
@@ -527,7 +545,7 @@ function load_file(filename::AbstractString)
     asdf_constructors′["tag:stsci.edu:asdf/core/ndarray-chunk-1.0.0"] = construct_yaml_ndarray_chunk
     asdf_constructors′["tag:stsci.edu:asdf/core/chunked-ndarray-1.0.0"] = construct_yaml_chunked_ndarray
 
-    metadata = YAML.load(io, asdf_constructors′)
+    metadata = YAML.load(io, asdf_constructors′, multi_constructors)
     # lazy_block_headers.block_headers = find_all_blocks(io, position(io))
     lazy_block_headers.block_headers = find_all_blocks(io)
     return ASDFFile(filename, metadata, lazy_block_headers)