docs: improve README and dataset display formatting

Author: Beforerr

README.md

@@ -1,24 +1,20 @@
 # CommonDataFormat.jl
 
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaspacephysics.github.io/CommonDataFormat.jl/dev/)
 [![Build Status](https://github.com/JuliaSpacePhysics/CommonDataFormat.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/JuliaSpacePhysics/CommonDataFormat.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/JuliaSpacePhysics/CommonDataFormat.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaSpacePhysics/CommonDataFormat.jl)
 
-A Julia package for reading Common Data Format (CDF) files, widely used in space physics for storing multidimensional data arrays and metadata. See [CDFDatasets.jl](https://github.com/JuliaSpacePhysics/CDFDatasets.jl) for a high-level interface.
+A Julia package for reading [Common Data Format (CDF)](https://cdf.gsfc.nasa.gov/) files, widely used in space physics for storing multidimensional data arrays and metadata. See [CDFDatasets.jl](https://github.com/JuliaSpacePhysics/CDFDatasets.jl) for a high-level interface.
+
+**Installation**: at the Julia REPL, run `using Pkg; Pkg.add("CommonDataFormat")`
+
+**Documentation**: [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaspacephysics.github.io/CommonDataFormat.jl/dev/)
 
 ## Features
 
 - **Pure Julia implementation** - No external dependencies on CDF libraries
 - **Efficient data access** - Memory-mapped access for data and attributes, super fast decompression using [`LibDeflate`](https://github.com/jakobnissen/LibDeflate.jl)
 - **[DiskArrays.jl](https://github.com/JuliaIO/DiskArrays.jl) integration** - Lazy representation of data on hard disk with AbstractDiskArray interface
 
-## Installation
-
-```julia
-using Pkg
-Pkg.add("CommonDataFormat")
-```
-
 ## Quick Start
 
 ```julia

docs/src/index.md

@@ -4,7 +4,24 @@ CurrentModule = CommonDataFormat
 
 # CommonDataFormat.jl
 
-A Julia package for reading Common Data Format (CDF) files.
+A Julia package for reading [Common Data Format (CDF)](https://cdf.gsfc.nasa.gov/) files, widely used in space physics for storing multidimensional data arrays and metadata. See [CDFDatasets.jl](https://github.com/JuliaSpacePhysics/CDFDatasets.jl) for a high-level interface.
+
+## Installation
+
+```julia
+using Pkg
+Pkg.add("CommonDataFormat")
+```
+
+## Quick Start
+
+```@example cdf
+using CommonDataFormat
+
+# Load a CDF file
+omni_file = joinpath(pkgdir(CommonDataFormat), "data/omni_coho1hr_merged_mag_plasma_20240901_v01.cdf")
+ds = CDFDataset(omni_file)
+```
 
 ## API Reference
 

src/dataset.jl

@@ -113,12 +113,18 @@ Base.haskey(cdf::CDFDataset, var_name::String) = var_name in keys(cdf)
 
 Base.iterate(cdf::CDFDataset, state = 1) = state > length(cdf) ? nothing : (cdf[keys(cdf)[state]], state + 1)
 
-function Base.show(io::IO, ::MIME"text/plain", cdf::CDFDataset)
-    println(io, typeof(cdf), ":", cdf.filename)
-    println(io, "variables")
-    for var in keys(cdf)
-        println(io, "  $var")
+function Base.show(io::IO, m::MIME"text/plain", cdf::CDFDataset)
+    println(io, typeof(cdf))
+    println(io, "path: ", cdf.filename)
+    println(io, "variables:")
+    for key in keys(cdf)
+        var = cdf[key]
+        print(io, "  $key : ", size(var), " ", DataType(var.vdr.data_type))
+        !isempty(var) && print(io, " [", var[1], " … ", var[end], "]")
+        println(io)
     end
     println(io, cdf.cdr)
+    print(io, "attributes: ")
+    show(io, m, cdf.attrib)
     return
 end

src/records/records.jl

@@ -85,15 +85,13 @@ function Base.show(io::IO, cdr::CDR)
     flag_info = decode_cdr_flags(cdr.flags)
 
     println(io, "CDR (CDF Descriptor Record):")
-    # println(io, "  Record Size: $(cdr.header.record_size) bytes")
-    # println(io, "  Record Type: $(cdr.header.record_type)")
-    println(io, "  GDR Offset: $(string(cdr.gdr_offset, base = 16, pad = 8))")
     println(io, "  Version: $(cdr.version).$(cdr.release).$(cdr.increment)")
     println(io, "  Encoding: $(cdr.encoding)")
     println(io, "  Flags: 0x$(string(cdr.flags, base = 16, pad = 8))")
     println(io, "    - Majority: $(majority(cdr))")
     println(io, "    - Single File Format: $(flag_info.single_file_format)")
     println(io, "    - Checksum Used: $(flag_info.checksum_used)")
     println(io, "    - MD5 Checksum: $(flag_info.md5_checksum)")
-    return println(io, "  Identifier: $(cdr.identifier)")
+    println(io, "  Identifier: $(cdr.identifier)")
+    return
 end

test/runtests.jl

@@ -28,6 +28,7 @@ end
     @test ds.compression == CDF.NoCompression
     @test first(ds) == ds["var"]
     @test occursin("Version: 3.9.0", string(ds))
+    display(ds)
 end
 
 @testset "Compressed cdf file (gzip)" begin