Revert "convert doctests with file size output to examples"

This reverts commit c411449.

docs/src/model_setup/lagrangian_particles.md

@@ -108,17 +108,43 @@ Particle properties can be written to disk using JLD2 or NetCDF.
 
 When writing to JLD2 you can pass `model.particles` as part of the named tuple of outputs.
 
-```@example particles
+```@meta
+DocTestFilters = r"└── file size: [0-9]*.[0-9]* KiB"
+```
+
+```jldoctest particles
 JLD2OutputWriter(model, (particles=model.particles,), filename="particles", schedule=TimeInterval(15))
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(15 seconds):
+├── filepath: ./particles.jld2
+├── 1 outputs: particles
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 17.6 KiB
 ```
 
 When writing to NetCDF you should write particles to a separate file as the NetCDF dimensions differ for
 particle trajectories. You can just pass `model.particles` straight to `NetCDFOutputWriter`:
 
-```@example particles
+```jldoctest particles
 NetCDFOutputWriter(model, model.particles, filename="particles.nc", schedule=TimeInterval(15))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(15 seconds):
+├── filepath: ./particles.nc
+├── dimensions: particle_id(10), time(0)
+├── 1 outputs: particles
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 9.9 KiB
 ```
 
 !!! warn "Outputting custom particle properties to NetCDF"
     NetCDF does not support arbitrary data types. If you need to write custom particle properties to disk
     that are not supported by NetCDF then you should use JLD2 (which should support almost any Julia data type).
+
+```@meta
+DocTestFilters = nothing
+```

docs/src/model_setup/output_writers.md

@@ -50,7 +50,7 @@ passing it a dictionary of (label, field) pairs and any indices for slicing if y
 Saving the u velocity field and temperature fields as full 3D fields, surface 2D slices, and
 1D columns to separate NetCDF files:
 
-```@example netcdf1
+```jldoctest netcdf1
 using Oceananigans
 
 grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1))
@@ -63,26 +63,53 @@ fields = Dict("u" => model.velocities.u, "c" => model.tracers.c)
 
 simulation.output_writers[:field_writer] =
     NetCDFOutputWriter(model, fields, filename="more_fields.nc", schedule=TimeInterval(60))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(1 minute):
+├── filepath: ./more_fields.nc
+├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0)
+├── 2 outputs: (c, u)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 14.9 KiB
 ```
 
-```@example netcdf1
+```jldoctest netcdf1
 simulation.output_writers[:surface_slice_writer] =
     NetCDFOutputWriter(model, fields, filename="another_surface_xy_slice.nc",
                        schedule=TimeInterval(60), indices=(:, :, grid.Nz))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(1 minute):
+├── filepath: ./another_surface_xy_slice.nc
+├── dimensions: zC(1), zF(1), xC(16), yF(16), xF(16), yC(16), time(0)
+├── 2 outputs: (c, u)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 14.9 KiB
 ```
 
-```@example netcdf1
+```jldoctest netcdf1
 simulation.output_writers[:averaged_profile_writer] =
     NetCDFOutputWriter(model, fields,
                        filename = "another_averaged_z_profile.nc",
                        schedule = AveragedTimeInterval(60, window=20),
                        indices = (1, 1, :))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(1 minute):
+├── filepath: ./another_averaged_z_profile.nc
+├── dimensions: zC(16), zF(17), xC(1), yF(1), xF(1), yC(1), time(0)
+├── 2 outputs: (c, u) averaged on AveragedTimeInterval(window=20 seconds, stride=1, interval=1 minute)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 17.6 KiB
 ```
 
 `NetCDFOutputWriter` also accepts output functions that write scalars and arrays to disk,
 provided that their `dimensions` are provided:
 
-```@example
+```jldoctest
 using Oceananigans
 
 Nx, Ny, Nz = 16, 16, 16
@@ -120,13 +147,22 @@ simulation.output_writers[:things] =
     NetCDFOutputWriter(model, outputs,
                        schedule=IterationInterval(1), filename="things.nc", dimensions=dims, verbose=true,
                        global_attributes=global_attributes, output_attributes=output_attributes)
+
+# output
+NetCDFOutputWriter scheduled on IterationInterval(1):
+├── filepath: ./things.nc
+├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0)
+├── 3 outputs: (profile, slice, scalar)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 17.8 KiB
 ```
 
 `NetCDFOutputWriter` can also be configured for `outputs` that are interpolated or regridded
 to a different grid than `model.grid`. To use this functionality, include the keyword argument
 `grid = output_grid`.
 
-```@example
+```jldoctest
 using Oceananigans
 using Oceananigans.Fields: interpolate!
 
@@ -143,6 +179,15 @@ output_writer = NetCDFOutputWriter(model, outputs;
                                    grid = coarse_grid,
                                    filename = "coarse_u.nc",
                                    schedule = IterationInterval(1))
+
+# output
+NetCDFOutputWriter scheduled on IterationInterval(1):
+├── filepath: ./coarse_u.nc
+├── dimensions: zC(4), zF(5), xC(1), yF(1), xF(1), yC(1), time(0)
+├── 1 outputs: u
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 14.6 KiB
 ```
 
 See [`NetCDFOutputWriter`](@ref) for more information.
@@ -163,7 +208,7 @@ of the function will be saved to the JLD2 file.
 
 Write out 3D fields for u, v, w, and a tracer c, along with a horizontal average:
 
-```@example jld2_output_writer
+```jldoctest jld2_output_writer
 using Oceananigans
 using Oceananigans.Utils: hour, minute
 
@@ -184,17 +229,36 @@ simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocitie
                                                           filename = "some_more_data.jld2",
                                                           schedule = TimeInterval(20minute),
                                                           init = init_save_some_metadata!)
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(20 minutes):
+├── filepath: ./some_more_data.jld2
+├── 3 outputs: (u, v, w)
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 29.1 KiB
 ```
 
 and a time- and horizontal-average of tracer `c` every 20 minutes of simulation time
 to a file called `some_more_averaged_data.jld2`
 
-```@example jld2_output_writer
+```jldoctest jld2_output_writer
 simulation.output_writers[:avg_c] = JLD2OutputWriter(model, (; c=c_avg),
                                                      filename = "some_more_averaged_data.jld2",
                                                      schedule = AveragedTimeInterval(20minute, window=5minute))
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(20 minutes):
+├── filepath: ./some_more_averaged_data.jld2
+├── 1 outputs: c averaged on AveragedTimeInterval(window=5 minutes, stride=1, interval=20 minutes)
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 17.9 KiB
 ```
 
+
 See [`JLD2OutputWriter`](@ref) for more information.
 
 ## Time-averaged output
@@ -229,7 +293,7 @@ AveragedTimeInterval(window=1 day, stride=1, interval=4 days)
 An `AveragedTimeInterval` schedule directs an output writer
 to time-average its outputs before writing them to disk:
 
-```@example averaged_time_interval
+```jldoctest averaged_time_interval
 using Oceananigans
 using Oceananigans.Units
 
@@ -240,4 +304,13 @@ simulation = Simulation(model, Δt=10minutes, stop_time=30days)
 simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocities,
                                                           filename = "even_more_averaged_velocity_data.jld2",
                                                           schedule = AveragedTimeInterval(4days, window=1day, stride=2))
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(4 days):
+├── filepath: ./even_more_averaged_velocity_data.jld2
+├── 3 outputs: (u, v, w) averaged on AveragedTimeInterval(window=1 day, stride=2, interval=4 days)
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 27.1 KiB
 ```

src/OutputWriters/jld2_output_writer.jl

@@ -110,7 +110,7 @@ Example
 
 Write out 3D fields for ``u``, ``v``, ``w``, and a tracer ``c``, along with a horizontal average:
 
-```@example
+```
 using Oceananigans
 using Oceananigans.Utils: hour, minute
 
@@ -131,15 +131,33 @@ simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocitie
                                                           filename = "some_data.jld2",
                                                           schedule = TimeInterval(20minute),
                                                           init = init_save_some_metadata!)
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(20 minutes):
+├── filepath: ./some_data.jld2
+├── 3 outputs: (u, v, w)
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 28.0 KiB
 ```
 
 and a time- and horizontal-average of tracer ``c`` every 20 minutes of simulation time
 to a file called `some_averaged_data.jld2`
 
-```@example
+```
 simulation.output_writers[:avg_c] = JLD2OutputWriter(model, (; c=c_avg),
                                                      filename = "some_averaged_data.jld2",
                                                      schedule = AveragedTimeInterval(20minute, window=5minute))
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(20 minutes):
+├── filepath: ./some_averaged_data.jld2
+├── 1 outputs: c averaged on AveragedTimeInterval(window=5 minutes, stride=1, interval=20 minutes)
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 17.8 KiB
 ```
 """
 function JLD2OutputWriter(model, outputs; filename, schedule,

src/OutputWriters/netcdf_output_writer.jl

@@ -265,7 +265,7 @@ Examples
 Saving the ``u`` velocity field and temperature fields, the full 3D fields and surface 2D slices
 to separate NetCDF files:
 
-```@example netcdf1
+```jldoctest netcdf1
 using Oceananigans
 
 grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1))
@@ -278,26 +278,53 @@ fields = Dict("u" => model.velocities.u, "c" => model.tracers.c)
 
 simulation.output_writers[:field_writer] =
     NetCDFOutputWriter(model, fields, filename="fields.nc", schedule=TimeInterval(60))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(1 minute):
+├── filepath: ./fields.nc
+├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0)
+├── 2 outputs: (c, u)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 14.9 KiB
 ```
 
-```@example netcdf1
+```jldoctest netcdf1
 simulation.output_writers[:surface_slice_writer] =
     NetCDFOutputWriter(model, fields, filename="surface_xy_slice.nc",
                        schedule=TimeInterval(60), indices=(:, :, grid.Nz))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(1 minute):
+├── filepath: ./surface_xy_slice.nc
+├── dimensions: zC(1), zF(1), xC(16), yF(16), xF(16), yC(16), time(0)
+├── 2 outputs: (c, u)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 14.9 KiB
 ```
 
-```@example netcdf1
+```jldoctest netcdf1
 simulation.output_writers[:averaged_profile_writer] =
     NetCDFOutputWriter(model, fields,
                        filename = "averaged_z_profile.nc",
                        schedule = AveragedTimeInterval(60, window=20),
                        indices = (1, 1, :))
+
+# output
+NetCDFOutputWriter scheduled on TimeInterval(1 minute):
+├── filepath: ./averaged_z_profile.nc
+├── dimensions: zC(16), zF(17), xC(1), yF(1), xF(1), yC(1), time(0)
+├── 2 outputs: (c, u) averaged on AveragedTimeInterval(window=20 seconds, stride=1, interval=1 minute)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 17.6 KiB
 ```
 
 `NetCDFOutputWriter` also accepts output functions that write scalars and arrays to disk,
 provided that their `dimensions` are provided:
 
-```@example
+```jldoctest
 using Oceananigans
 
 Nx, Ny, Nz = 16, 16, 16
@@ -334,13 +361,22 @@ simulation.output_writers[:things] =
     NetCDFOutputWriter(model, outputs,
                        schedule=IterationInterval(1), filename="things.nc", dimensions=dims, verbose=true,
                        global_attributes=global_attributes, output_attributes=output_attributes)
+
+# output
+NetCDFOutputWriter scheduled on IterationInterval(1):
+├── filepath: ./things.nc
+├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0)
+├── 3 outputs: (profile, slice, scalar)
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 17.8 KiB
 ```
 
 `NetCDFOutputWriter` can also be configured for `outputs` that are interpolated or regridded
 to a different grid than `model.grid`. To use this functionality, include the keyword argument
 `grid = output_grid`.
 
-```@example
+```jldoctest
 using Oceananigans
 using Oceananigans.Fields: interpolate!
 
@@ -357,6 +393,15 @@ output_writer = NetCDFOutputWriter(model, outputs;
                                    grid = coarse_grid,
                                    filename = "coarse_u.nc",
                                    schedule = IterationInterval(1))
+
+# output
+NetCDFOutputWriter scheduled on IterationInterval(1):
+├── filepath: ./coarse_u.nc
+├── dimensions: zC(4), zF(5), xC(1), yF(1), xF(1), yC(1), time(0)
+├── 1 outputs: u
+└── array type: Array{Float64}
+├── file_splitting: NoFileSplitting
+└── file size: 14.6 KiB
 ```
 """
 function NetCDFOutputWriter(model, outputs;

src/OutputWriters/windowed_time_average.jl

@@ -59,7 +59,7 @@ AveragedTimeInterval(window=2 days, stride=1, interval=4 days)
 An `AveragedTimeInterval` schedule directs an output writer
 to time-average its outputs before writing them to disk:
 
-```@example averaged_time_interval
+```jldoctest averaged_time_interval
 using Oceananigans
 using Oceananigans.Units
 
@@ -70,6 +70,15 @@ simulation = Simulation(model, Δt=10minutes, stop_time=30days)
 simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocities,
                                                           filename= "averaged_velocity_data.jld2",
                                                           schedule = AveragedTimeInterval(4days, window=2days, stride=2))
+
+# output
+JLD2OutputWriter scheduled on TimeInterval(4 days):
+├── filepath: ./averaged_velocity_data.jld2
+├── 3 outputs: (u, v, w) averaged on AveragedTimeInterval(window=2 days, stride=2, interval=4 days)
+├── array type: Array{Float64}
+├── including: [:grid, :coriolis, :buoyancy, :closure]
+├── file_splitting: NoFileSplitting
+└── file size: 27.6 KiB
 ```
 """
 function AveragedTimeInterval(interval; window=interval, stride=1)