[WIP] Documentation (take two) (#266)

* moving work to main repo * Change repo url in docs/make.jl * Small typo and fix of structure Co-authored-by: Fabian Gans <[email protected]>
JuliaDataCubes · Apr 13, 2022 · b299cba · b299cba
1 parent bfc872e
commit b299cba
Show file tree

Hide file tree

Showing 14 changed files with 81 additions and 347 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,9 +1,2 @@
 [deps]
-ESDLPlots = "d555b242-3f29-57aa-84ea-3df92a135dfd"
-Cairo = "159f3aea-2a34-519c-b102-8c37f9878175"
-ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-Fontconfig = "186bb1d3-e1f7-5a2c-a377-96d770f13627"
-ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
-Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
-WeightedOnlineStats = "bbac0a1f-7c9d-5672-960b-c6ca726e5d5d"
diff --git a/docs/docs2/Project.toml b/docs/docs2/Project.toml
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,47 +1,29 @@
-using ImageMagick, Documenter, ESDL, ESDLPlots, Cairo
-
-
-newcubedir = mktempdir()
-ESDLdir(newcubedir)
-# Download Cube subset
-if !isempty(ESDL.ESDLDefaults.cubedir[])
-  c = S3Cube()
-  csa = c[
-    region = "South America",
-    var = ["country_mask","c_emissions","gross", "net_ecosystem", "air_temperature_2m", "terrestrial_ecosystem", "land_surface_temperature"],
-    time = 2003:2006
-  ]
-  saveCube(csa,"southamericacube", chunksize=(90,90,92,1))
-  ESDL.ESDLDefaults.cubedir[] = joinpath(newcubedir,"southamericacube")
-end
-
-exampledir = joinpath(@__DIR__,"src","examples")
-allex = map(readdir(exampledir)) do fname
-  n = splitext(fname)[1]
-  n => joinpath("examples",fname)
-end
-
+using Documenter, ESDL
 
 makedocs(
-    modules = [ESDL, ESDLPlots],
-    clean   = true,
+    modules  = [ESDL],
+    clean    = true,
+    doctest  = false,
     format   = Documenter.HTML(),
     sitename = "ESDL.jl",
-    authors = "Fabian Gans",
-    pages    = [ # Compat: `Any` for 0.4 compat
+    authors  = "Fabian Gans",
+    pages    = [ 
         "Home" => "index.md",
-        "Examples" => allex,
-        "Manual" => Any[
-            "cube_access.md",
-            "analysis.md",
-            "plotting.md",
-            "iotools.md"
+        "Examples" => Any[
+            "Time Mean" => "examples/time_mean.md",
+            "Distributed Computations" => "examples/distributed.md",
+        ],
+        "API Documentation" => Any[
+            "Index" => "API/api_index.md",
+            "Accessing the Data Cube" => "API/cube_access.md",
+            "Analysis" => "API/analysis.md",
+            "Loading and Saving Results" => "API/iotools.md"
         ],
-        "Other functions" => "./lib/misc.md"
+        "Other functions" => "lib/misc.md"
         ]
 )
 
 deploydocs(
-    #deps   = Deps.pip("mkdocs", "python-markdown-math"),
-    repo   = "github.com/esa-esdl/ESDL.jl.git",
+    repo   = "github.com/JuliaDataCubes/ESDL.jl.git",
+    push_preview = true
 )
diff --git a/docs/src/analysis.md → docs/src/API/analysis.md b/docs/src/analysis.md → docs/src/API/analysis.md
diff --git a/docs/src/API/api_index.md b/docs/src/API/api_index.md
@@ -0,0 +1,4 @@
+## Index
+
+```@index
+```
diff --git a/docs/src/cube_access.md → docs/src/API/cube_access.md b/docs/src/cube_access.md → docs/src/API/cube_access.md
@@ -20,36 +20,28 @@ This returns a `Cube` object that contains some basics information about the cub
 
 ## Getting a data handle
 
-```@setup 1
+```julia
 using ESDL
 c=Cube()
 ```
 
-```@example 1
+```julia
 var=["c_emissions","air_temperature_2m"]
 time=(Date("2003-01-01"),Date("2003-12-31"))
 cubedata = subsetcube(c,lon=(30,31),lat=(50,51),time=time,variable=var)
 ```
 
 This returns a view into the Data Cube, on which further calculations can be applied.
-All keyword arguments default to the full range, so calling `subsetcube` without
-keyword arguments will return a view into the whole data cube.
-
-```@docs
-ESDL.Cubes.subsetcube
-```
-
 
 No data is read yet. In case you want to load some data into memory and store it in a Julia array, just use square-bracket indexing. For example, to read the first time step  of the first variable as a Lon-Lat array, just do
 
-```@example 1
+```julia
 cubedata[:,:,1,1]
 ```
 
 Here you can start to do some calculations on your sub-cube, see either
 [Analysis](@ref) for a list of methods provided by this framework or
-[Applying custom functions](@ref) to apply your own functions on the cube. If you just
-want to visualize the cube see this section [Plotting](@ref).
+[Applying custom functions](@ref) to apply your own functions on the cube.
 
 ## Extracting a list of lon/lat coordinates from a data cube
 
@@ -58,12 +50,12 @@ needed for the analysis. One can extract such a list by first creating a cube vi
 containing all the needed variables and then apply the `extractLonLats` function.
 
 ```@docs
-ESDL.Proc.CubeIO.extractLonLats
+    ESDL.Proc.extractLonLats
 ```
 
 Here is an example how to apply the function:
 
-```@example 1
+```julia
 cubedata = subsetcube(c,lon=(30,31),lat=(50,51),time=time,variable=var)
 ll       = [30.1 50.2;
             30.5 51.1;
@@ -74,20 +66,7 @@ cubenew  = extractLonLats(cubedata,ll)
 ## Cube Types
 
 While the `subsetcube` command returns an object of type `ZarrCube`, which represents a view into the ESDC, other cube operations will return different types of data cubes.
-The returned type will depend on the size of the returned cube. If it is small enough to fit into memory, it will be a `CubeMem`, otherwise a `ZArrayCube`. All these types of data cubes share the same interface defined by, which means you can index them, do calculation using `mapCube` or plot them using the commands described in [Plotting](@ref).
-
-
-```@docs
-ESDL.Cubes.CubeMem
-```
-
-```@docs
-ESDL.Cubes.ESDLZarr.ZArrayCube
-```
-
-```@docs
-ESDL.Cubes.OBS.S3Cube
-```
+The returned type will depend on the size of the returned cube. If it is small enough to fit into memory, it will be a `CubeMem`, otherwise a `ZArrayCube`. All these types of data cubes share the same interface defined by, which means you can index them, do calculation using `mapCube` or plot them.
 
 
 ## Cube Dimensions
@@ -98,30 +77,8 @@ field `values` representing the chosen latitudes. Similarly, a `VariableAxis` wi
 Variable names. Axes types are divided in categorical axes and axes represented by ranges. All of them
 are subtypes of the abstract type `CubeAxis`.
 
-```@docs
-ESDL.Cubes.Axes.CubeAxis
-```
-
-```@docs
-ESDL.Cubes.Axes.CategoricalAxis
-```
-
-```@docs
-ESDL.Cubes.Axes.RangeAxis
-```
-
-
-## Opening cloud-hosted Data Cubes
-
-When you
-
-```@docs
-S3Cube
-```
-
-
 ## List of known regions
 
 ```@docs
-ESDL.Cubes.ESDLZarr.known_regions
+    ESDL.known_regions
 ```
diff --git a/docs/src/API/iotools.md b/docs/src/API/iotools.md
@@ -0,0 +1,3 @@
+# Loading and saving results
+
+    ESDL.ESDLTools.@loadOrGenerate
diff --git a/docs/src/examples/Time Mean.md → docs/src/examples/distributed.md b/docs/src/examples/Time Mean.md → docs/src/examples/distributed.md
@@ -1,12 +1,3 @@
-## How to calculate a time mean
-
-````@jldoctest
-using ESDL
-c = Cube()
-citaly = c[var = ["air_temperature_2m", "evaporation"], region="Italy", time=2001:2003]
-mapslices(mean ∘ skipmissing, c, dims="Time")
-````
-
 ## Distributed calculations
 
 ### Local machine

diff --git a/docs/src/examples/time_mean.md b/docs/src/examples/time_mean.md
@@ -0,0 +1,9 @@
+## How to calculate a time mean
+
+````@jldoctest
+using ESDL
+c = Cube()
+citaly = c[var = ["air_temperature_2m", "evaporation"], region="Italy", time=2001:2003]
+mapslices(mean ∘ skipmissing, c, dims="Time")
+````
+
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -20,7 +20,6 @@ You can find some example Jupyter Notebooks using *ESDL.jl* [here](https://githu
 ```@contents
 Pages = [
     "cube_access.md",
-    "plotting.md",
     "analysis.md",
     "iotools.md",
 ]
@@ -30,9 +29,4 @@ Depth = 3
 ## Acknowledgements
 
 The development of this package was funded by ESA STSE and implemented by
-the Max-Planck-Institute for Biogeochemistry.
-
-## Index
-
-```@index
-```
+the Max-Planck-Institute for Biogeochemistry.
diff --git a/docs/src/iotools.md b/docs/src/iotools.md
diff --git a/docs/src/lib/misc.md b/docs/src/lib/misc.md
@@ -1,7 +1,5 @@
 # Other functions
 
 ```@docs
-getAxis
-caxes
-getNpY
+    getNpY
 ```
diff --git a/docs/src/plotting.md b/docs/src/plotting.md