docs: Data orientation note + merge sections (#58)

Notes how underlying data layout maps to Makie.jl when using
heatmap/image/etc. Also merges the Intro and Introduction sections

Author: icweaver

docs/make.jl

@@ -16,7 +16,6 @@ makedocs(;
     ),
     pages = [
         "Home" => "index.md",
-        "Introduction" => "intro.md",
         "Examples" => [
             "JWST" => "examples/jwst.md",
             "Roman" => "examples/roman.md",

docs/src/examples/jwst.md

@@ -53,3 +53,6 @@ Colorbar(fig[1, 2], hm; label = "Counts")
 
 fig
 ```
+
+!!! note
+    By default, Makie.jl places the origin in the lower left corner and transposes the data, matching the convention used in the Python workshop example. To have the plot orientation match the data orientation instead, modify the above plot command to: `heatmap(img_sci'; axis = (; yreversed = true))`. See also [`permutedims`](https://docs.julialang.org/en/v1/base/arrays/#Base.permutedims) for a more general alternative to the adjoint (conjugate transpose) operation: [`'`](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#Base.adjoint).

docs/src/examples/roman.md

@@ -55,3 +55,6 @@ Colorbar(fig[1, 2], hm; label = "Counts")
 
 fig
 ```
+
+!!! note
+    By default, Makie.jl places the origin in the lower left corner and transposes the data, matching the convention used in the Python workshop example. To have the plot orientation match the data orientation instead, modify the above plot command to: `heatmap(img_sci'; axis = (; yreversed = true))`. See also [`permutedims`](https://docs.julialang.org/en/v1/base/arrays/#Base.permutedims) for a more general alternative to the adjoint (conjugate transpose) operation: [`'`](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#Base.adjoint).

docs/src/index.md

@@ -2,35 +2,127 @@
 
 A new [Advanced Scientific Data Format (ASDF)](https://asdf-standard.readthedocs.io/en/latest/index.html) package, written in Julia.
 
-## Quickstart
+## Introduction
 
-### Installation
+The ASDF file format is based on the human-readable [YAML](http://yaml.org/) standard, extended with efficient binary blocks to store array data. Basic arithmetic types (`Bool`, `Int`, `Float`, `Complex`) and `String` types are supported out of the box. Other types (structures) need to be declared to be supported.
+
+ASDF supports arbitrary array strides, both C (Python) and Fortran (Julia) memory layouts, as well as compression. The YAML metadata can contain arbitrary information corresponding to scalars, arrays, or dictionaries.
+
+The ASDF file format targets a similar audience as the [HDF5](https://www.hdfgroup.org/solutions/hdf5/) format.
+
+## Installation
 
 ```julia-repl
 pkg> add ASDF, OrderedCollections
 ```
 
-### Usage
-
-```@example quickstart
+```@repl intro
 using ASDF, OrderedCollections
+```
 
-doc = OrderedDict(
-    "field_1" => [5, 6, 7, 8],
-    "field_2" => ["up", "down", "left", "right"],
-    "field_3" => OrderedDict(
-        "field_3a" => ["apple", "orange", "pear"],
-        "field_3b" => [1.0, 2.0, 3.0],
-    )
-)
+!!! note
+    We use an `OrderedDict` from [OrderedCollections.jl](https://github.com/JuliaCollections/OrderedCollections.jl) to preserve the order of data on write and load, and to maximize compatibility with YAML.jl.
 
-save("example.asdf", doc)
+## Getting started
+
+ASDF files are initially created as a dictionary with arbitrarily nested data:
+
+```@example intro
+af_payload = OrderedDict("field_1" => [5, 6, 7, 8], "field_2" => ["up", "down", "left", "right"], "field_3" => OrderedDict("field_3a" => ["apple", "orange", "pear"], "field_3b" => [1.0, 2.0, 3.0]))
 ```
 
-```@example quickstart
-af = load("example.asdf")
+ASDF.jl is registered with [FileIO.jl](https://juliaio.github.io/FileIO.jl/stable/), so this data can be written to the ASDF file format with the generic [`save`](@ref) function:
+
+```@example intro
+save("intro.asdf", af_payload)
 ```
 
-```@example quickstart
+The saved file contains the following human-readable contents:
+
+!!! details "View file"
+    ```@example intro
+    read("intro.asdf", String) |> print
+    ```
+
+which can be loaded back with FileIO.jl's generic [`load`](@ref) function:
+
+```@example intro
+af = load("intro.asdf")
+```
+
+This is stored as an [`ASDF.ASDFFile`](@ref). To change the number of rows shown, pass this object to [`ASDF.info`](@ref):
+
+```@example intro
 ASDF.info(af; max_rows = 3)
 ```
+
+It contains a `metadata` field, which is a new dictionary that merges information about this library (stored under the `asdf_library` key) with the original user-defined `af_payload` dictionary. For convenience, `af.metadata[<key>]` can be accessed directly as `af[key]`. Since the underlying data is a dictionary, it can be modified in the standard way:
+
+```@example intro
+af["field_1"] = [50, 60, 70, 80]
+```
+
+The convenience syntax can also be used to save the modified `ASDF.ASDFFile` object directly:
+
+```@example intro
+save("intro_modified.asdf", af)
+```
+
+!!! details "View file"
+    ```@example intro
+    read("intro_modified.asdf", String) |> print
+    ```
+
+## Array storage
+
+By default, array data is written inline as a literal to the ASDF file. This can be stored and later accessed more efficiently by wrapping your data in an [`ASDF.NDArrayWrapper`](@ref). This allows for your data to be stored as a binary via the `inline = false` keyword (default), which can be further optimized by specifying a supported [compression algorithm](@ref ASDF.Compression) to use via the `compression` keyword:
+
+```@example intro
+af_payload = OrderedDict("meta" => OrderedDict("my" => OrderedDict("nested" => "metadata")), "data" => ASDF.NDArrayWrapper([1, 2, 3, 4]; compression = ASDF.C_Bzip2))
+
+save("intro_compressed.asdf", af_payload)
+
+af = load("intro_compressed.asdf")
+```
+
+!!! details "View file"
+    ```julia-repl
+    julia> read("intro_compressed.asdf", String) |> print
+    #ASDF 1.0.0
+    #ASDF_STANDARD 1.6.0
+    # This is an ASDF file <https://asdf-standard.readthedocs.io/>
+    %YAML 1.1
+    %TAG ! tag:stsci.edu:asdf/
+    ---
+    !core/asdf-1.1.0
+    meta:
+      my:
+        nested: "metadata"
+    data: !core/ndarray-1.1.0
+      source: 0
+      shape:
+        - 4
+      datatype: "int64"
+      byteorder: "little"
+    asdf_library: !core/software-1.0.0
+      name: "ASDF.jl"
+      author: "Erik Schnetter <schnetter@gmail.com>"
+      homepage: "https://github.com/JuliaAstro/ASDF.jl"
+      version: "2.0.0"
+    ...
+    �BLK0   f�0xj�sq���r#ASDF BLOCK INDEX
+    %YAML 1.1
+    ---
+    [463,]
+    ...
+    ```
+
+Using `NDArrayWrapper` allows for the wrapped data to be lazily accessed as a strided view. To access the underlying data, use the `[]` (dereference) syntax:
+
+```@example intro
+af["data"][] == [1, 2, 3, 4]
+```
+
+## Tagged objects
+
+Come back soon to see how custom Julia objects can be handled in ASDF.jl.