Merge pull request #395 from danlooo/refactor_documentation

Refactor and Simplify Documentation
JuliaDataCubes · May 23, 2024 · 7a80fe5 · 7a80fe5
2 parents b4bf448 + 778f635
commit 7a80fe5
Show file tree

Hide file tree

Showing 26 changed files with 748 additions and 761 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,6 +1,7 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Bonito = "824d6782-a2ef-11e9-3a09-e5662e0c26f8"
+CFTime = "179af706-886a-5703-950a-314cd64e0468"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
@@ -21,6 +22,7 @@ MultivariateStats = "6f286f6a-111f-5878-ab1e-185364afe411"
 NetCDF = "30363a11-5582-574a-97bb-aa9a979735b9"
 OnlineStats = "a15396b6-48d5-5d58-9928-6d29437db91e"
 PlotUtils = "995b91a9-d308-5afd-9ec6-746e21dbc043"
+Rasters = "a3a2b9e3-a471-40c9-b274-f788e487c689"
 SkipNan = "aed68c70-c8b0-4309-8cd1-d392a74f991a"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"

diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
@@ -11,16 +11,17 @@ export default defineConfig({
   cleanUrls: true,
   outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
   ignoreDeadLinks: true,
-  
+
   markdown: {
     math: true,
     config(md) {
       md.use(tabsMarkdownPlugin),
-      md.use(mathjax3)
+        md.use(mathjax3)
     },
     theme: {
       light: "github-light",
-      dark: "github-dark"}
+      dark: "github-dark"
+    }
   },
   themeConfig: {
     outline: 'deep',
@@ -34,73 +35,84 @@ export default defineConfig({
     },
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Getting Started', link: '/getting_started' },
-      { text: 'User Guide',
+      { text: 'Get Started', link: '/get_started' },
+      {
+        text: 'User Guide',
         items: [
-          { text: 'Creating YAXArrays and Datasets', link: '/UserGuide/creating' },
-          { text: 'Indexing and subsetting', link: '/UserGuide/indexing_subsetting' },
-          { text: 'Saving YAXArrays and Datasets', link: '/UserGuide/saving' },
-          { text: 'Setting chunks size', link: '/UserGuide/setchuncks' },
-          { text: 'Apply functions on YAXArrays', link: '/UserGuide/applyfunctions' },
-          { text: 'Create Cube from function', link: '/UserGuide/create_cube_from_function' },
-          { text: 'Group by', link: '/UserGuide/group_by' },
-          { text: 'Distributed computing', link: '/UserGuide/distributed' },
-          { text: 'Open NetCDF', link: '/UserGuide/openNetCDF' },
-          { text: 'Open Zarr (Store)', link: '/UserGuide/openZarr' },
-      ]},
-      { text: 'Tutorials',
+          { text: 'Types', link: '/UserGuide/types' },
+          { text: 'Read', link: '/UserGuide/read' },
+          { text: 'Write', link: '/UserGuide/write' },
+          { text: 'Convert', link: '/UserGuide/convert' },
+          { text: 'Create', link: '/UserGuide/create' },
+          { text: 'Select', link: '/UserGuide/select' },
+          { text: 'Compute', link: '/UserGuide/compute' },
+          { text: 'Chunk', link: '/UserGuide/chunk' },
+          { text: 'Group', link: '/UserGuide/group' },
+          { text: 'Combine', link: '/UserGuide/combine' },
+          { text: 'FAQ', link: '/UserGuide/faq' }
+        ]
+      },
+      {
+        text: 'Tutorials',
         items: [
           { text: 'Overview', link: '/tutorials/tutorial' },
           { text: 'Plotting maps', link: '/tutorials/plottingmaps' },
           { text: 'Mean Seasonal Cycle', link: '/tutorials/mean_seasonal_cycle' },
-          { text: 'ESDL studies',
+          {
+            text: 'ESDL studies',
             items: [
               { text: 'ESDL study 1', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_1.jl' },
               { text: 'ESDL study 2', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_2.jl' },
               { text: 'ESDL study 3', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_3.jl' },
               { text: 'ESDL study 4', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_4.jl' },
             ]
           },
-      ]},
-      { text: 'How do I?',
-      items: [
-        { text: 'How do I ...', link: '/HowdoI/howdoi' },
-        { text: 'Contribute to docs', link: '/HowdoI/contribute' },
-        { text: 'Contributors', link: '/contributors' }
-    ]},
+          { text: 'Other Tutorials', link: '/tutorials/other_tutorials' },
+        ]
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Contribute', link: 'development/contribute' },
+          { text: 'Contributors', link: 'development/contributors' }
+        ]
+      },
     ],
 
     sidebar: [
-      { text: 'Getting Started', link: '/getting_started' },
-      { text: 'User Guide',
+      { text: 'Get Started', link: '/get_started' },
+      { text: 'API Reference', link: 'api' },
+      {
+        text: 'User Guide',
         items: [
-          { text: 'Creating YAXArrays and Datasets', link: '/UserGuide/creating' },
-          { text: 'Indexing and subsetting', link: '/UserGuide/indexing_subsetting' },
-          { text: 'Saving YAXArrays and Datasets', link: '/UserGuide/saving' },
-          { text: 'Setting chunks size', link: '/UserGuide/setchuncks' },
-          { text: 'Apply functions on YAXArrays', link: '/UserGuide/applyfunctions' },
-          { text: 'Create Cube from function', link: '/UserGuide/create_cube_from_function' },
-          { text: 'Group by', link: '/UserGuide/group_by' },
-          { text: 'Distributed computing', link: '/UserGuide/distributed' },
-          { text: 'Open NetCDF', link: '/UserGuide/openNetCDF' },
-          { text: 'Open Zarr (Store)', link: '/UserGuide/openZarr' },
-      ]},
-      { text: 'Tutorials',
+          { text: 'Types', link: '/UserGuide/types' },
+          { text: 'Read', link: '/UserGuide/read' },
+          { text: 'Write', link: '/UserGuide/write' },
+          { text: 'Convert', link: '/UserGuide/convert' },
+          { text: 'Create', link: '/UserGuide/create' },
+          { text: 'Select', link: '/UserGuide/select' },
+          { text: 'Compute', link: '/UserGuide/compute' },
+          { text: 'Chunk', link: '/UserGuide/chunk' },
+          { text: 'Group', link: '/UserGuide/group' },
+          { text: 'Combine', link: '/UserGuide/combine' },
+          { text: 'FAQ', link: '/UserGuide/faq' }
+        ]
+      },
+      {
+        text: 'Tutorials',
         items: [
-          { text: 'Overview', link: '/tutorials/tutorial' },
           { text: 'Plotting maps', link: '/tutorials/plottingmaps' },
-          { text: 'Mean Seasonal Cycle', link: '/tutorials/mean_seasonal_cycle' }
-      ]},
-      { text: 'How do I?',
-      items: [
-        { text: 'How do I ...', link: '/HowdoI/howdoi' },
-        { text: 'Contribute to docs', link: '/HowdoI/contribute' },
-    ]},
-    { text: 'Contributors', link: '/contributors' },
-    { text: 'API',
-    items: [
-      { text: 'API Reference', link: 'api' },
-    ]},
+          { text: 'Mean Seasonal Cycle', link: '/tutorials/mean_seasonal_cycle' },
+          { text: 'Other Tutorials', link: '/tutorials/other_tutorials' },
+        ]
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Contribute', link: 'development/contribute' },
+          { text: 'Contributors', link: 'development/contributors' }
+        ]
+      },
     ],
     editLink: {
       pattern: 'https://github.com/JuliaDataCubes/YAXArrays.jl/edit/master/docs/src/:path'

diff --git a/docs/src/UserGuide/applyfunctions.md b/docs/src/UserGuide/applyfunctions.md
diff --git a/docs/src/UserGuide/setchuncks.md → docs/src/UserGuide/chunk.md b/docs/src/UserGuide/setchuncks.md → docs/src/UserGuide/chunk.md
@@ -1,4 +1,4 @@
-# Set chunks
+# Chunk YAXArrays
 
 > [!IMPORTANT]
 > Thinking about chunking is important when it comes to analyzing your data, because in most situations this will not fit into memory, hence having the fastest read access to it is crucial for your workflows. For example, for geo-spatial data do you want fast access on time or space, or... think about it.

diff --git a/docs/src/UserGuide/combine.md b/docs/src/UserGuide/combine.md
@@ -0,0 +1,34 @@
+# Combine YAXArrays
+
+Data is often scattered across multiple files and corresponding arrays, e.g. one file per time step.
+This section describes methods on how to combine them into a single YAXArray.
+
+## `cat` along an existing dimension
+
+Here we use `cat` to combine two arrays consisting of data from the first and the second half of a year into one single array containing the whole year.
+We glue the arrays along the first dimension using `dims = 1`:
+The resulting array `whole_year` still has one dimension, i.e. time, but with 12 instead of 6 elements.
+
+````@example cat
+using YAXArrays
+
+first_half = YAXArray((Dim{:time}(1:6),), rand(6))
+second_half = YAXArray((Dim{:time}(7:12),), rand(6))
+whole_year = cat(first_half, second_half, dims = 1)
+````
+
+## `concatenatecubes` to a new dimension
+
+Here we use `concatenatecubes` to combine two arrays of different variables that have the same dimensions.
+The resulting array `combined` has an additional dimension `variable` indicating from which array the element values originates.
+Note that using a `Dataset` instead is a more flexible approach in handling different variables.
+
+````@example concatenatecubes
+using YAXArrays
+
+temperature = YAXArray((Dim{:time}(1:6),), rand(6))
+precipitation = YAXArray((Dim{:time}(1:6),), rand(6))
+cubes = [temperature,precipitation]
+var_axis = Dim{:variable}(["temp", "prep"])
+combined = concatenatecubes(cubes, var_axis)
+````