update docs

docs/make.jl

@@ -1,14 +1,23 @@
 using Pkg
 Pkg.activate(@__DIR__)
-CI = get(ENV, "CI", nothing) == "true"
-using Documenter, NCDatasets, CommonDataModel
+using Documenter, NCDatasets, CommonDataModel, UUIDs
+
+CommonDataModel_path = realpath(joinpath(dirname(pathof(CommonDataModel)),".."))
+CommonDataModel_remote = (
+    Remotes.GitHub("JuliaGeo","CommonDataModel.jl"),
+    string("v",Pkg.dependencies()[UUID("1fbeeb36-5f17-413c-809b-666fb144f157")].version))
+
 
 makedocs(
     modules = [NCDatasets, CommonDataModel],
+    remotes = Dict(
+        CommonDataModel_path => CommonDataModel_remote,
+    ),
     sitename = "NCDatasets.jl",
     doctest = false,
     format = Documenter.HTML(
-        prettyurls = CI,
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        canonical = "https://alexander-barth.github.io/NCDatasets.jl",
     ),
     pages = [
         "Introduction" => "index.md",
@@ -24,7 +33,4 @@ makedocs(
     checkdocs = :none,
 )
 
-if CI
-    deploydocs(repo = "github.com/Alexander-Barth/NCDatasets.jl.git",
-               target = "build")
-end
+deploydocs(repo = "github.com/Alexander-Barth/NCDatasets.jl.git")

docs/src/issues.md

@@ -124,7 +124,7 @@ You can run `pwd()` to determine the current working directory. Note that the in
 can be different depending you how you start julia (from the command line or from jupyter notebook for example).
 Julia need to be restarted after this file is placed in the your working directory.
 
-## Using non-official julia builds
+## version `CURL_4' not found
 
 Julia and [NetCDF_jll](https://github.com/JuliaBinaryWrappers/NetCDF_jll.jl) have several common dependencies (curl, MbedTLS, zlib).
 Non-official julia builds will work only if they use exactly the same library version as those used to compile NetCDF. This is unlikely to be the case in general and outside of our control. Therefore non-official julia builds are not supported.
@@ -150,23 +150,22 @@ You will likely have similar issues with julia installed from other package mana
 the [offical julia builds](https://julialang.org/downloads/).
 
 
-## version `CURL_4' not found
-
-If you see the following error:
+Even when the official build of julia, this error can occur on Linux if an incompatible library is loaded when the user set `LD_LIBRARY_PATH` and `LD_PRELOAD`:
 
 ```
 ERROR: LoadError: InitError: could not load library "/home/user/.julia/artifacts/461703969206dd426cc6b4d99f69f6ffab2a9779/lib/libnetcdf.so"
 /usr/lib/x86_64-linux-gnu/libcurl.so: version `CURL_4' not found (required by /home/user/.julia/artifacts/461703969206dd426cc6b4d99f69f6ffab2a9779/lib/libnetcdf.so)
 ```
 
-make sure that you are using the [offical julia builds](https://julialang.org/downloads/) (see above) and that your `LD_LIBRARY_PATH` and `LD_PRELOAD` are empty.
-You can verify this by running the following commands in a terminal:
+Please make sure that your `LD_LIBRARY_PATH` and `LD_PRELOAD` are empty or verify that the all loaded libraries are binary compatible.
+You can check these environement variables by running the following commands in a terminal:
 
 ```bash
 echo $LD_PRELOAD
 echo $LD_LIBRARY_PATH
 ```
 
+If you must set `$LD_LIBRARY_PATH` for some application, consider to use a [wrapper script](https://www.hpc.dtu.dk/?page_id=1180) for this application or recompiling the application with the `-rpath` linker option rather than setting this variable globally.
 
 
 ## Corner cases

docs/src/other.md

@@ -163,10 +163,9 @@ NCDatasets.@select
 
 ## Fill values and missing values
 
-In the NetCDF [CF conventions](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#missing-data) there are the attributes `_FillValue` (single scalar)  and `missing_value` (single scalar or possibly a vector with multiple missing values).
-While missing values are represented as a special [`Missing` type](https://docs.julialang.org/en/v1/manual/missing/) in Julia, for some application it is more convenient to use another special value like the special floating point number `NaN`.
-For example:
+In the NetCDF [CF conventions](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#missing-data) there are the attributes `_FillValue` (single scalar)  and `missing_value` (single scalar or possibly a vector with multiple missing values). Value in the netCDF file matching, these attributes are replaced by the [`Missing` type](https://docs.julialang.org/en/v1/manual/missing/) in Julia per default. However, for some applications, it is more convenient to use another special value like the special floating point number `NaN`.
 
+For example, this is a netCDF file where the variable `var` contains a `missing` which is automatically replaced by the fill value 9999.
 
 ```julia
 using NCDatasets
@@ -175,7 +174,7 @@ ds = NCDataset("example.nc","c")
 defVar(ds,"var",data,("lon","lat"),fillvalue = 9999.)
 ```
 
-Get the raw data as stored in the NetCDF file:
+The raw data as stored in the NetCDF file is available using the property `.var`:
 
 ```julia
 ds["var"].var[:,:]
@@ -184,7 +183,7 @@ ds["var"].var[:,:]
 #  9999.0  20.0  30.0
 ```
 
-Get the data using CF transformation, in particular the fill value is replaced by `missing`:
+Per default, the fill value is replaced by `missing` when indexing `ds["var"]`:
 
 ```julia
 ds["var"][:,:]
@@ -193,7 +192,7 @@ ds["var"][:,:]
 #  missing  20.0  30.0
 ```
 
-The function `nomissing` allows to replace all missing value with a different values:
+The function `nomissing` allows to replace all missing value with a different value like `NaN`:
 
 ```julia
 var_nan = nomissing(ds["var"][:,:],NaN)
@@ -203,7 +202,7 @@ var_nan = nomissing(ds["var"][:,:],NaN)
 close(ds)
 ```
 
-Such substitution can also be made more automatically using the experimental parameter` maskingvalue` that can be user per variable:
+Such substitution can also be made more automatic using the experimental parameter `maskingvalue` that can be user per variable:
 
 
 ```julia
@@ -227,7 +226,7 @@ ds["var"][:,:]
 close(ds)
 ```
 
-Note choosing the `maskingvalue` affects the element type of the NetCDF variable using julia type promotion rules, in particular note that following vector:
+Note, choosing the `maskingvalue` affects the element type of the NetCDF variable using julia type promotion rules, in particular note that following vector:
 
 
 ```julia
@@ -239,8 +238,7 @@ Note choosing the `maskingvalue` affects the element type of the NetCDF variable
 
 is a vector with the element type `Float64` and not `Union{Float64,Int}`. All integers
 are thus promoted to floating point number as `NaN` is a `Float64`.
-
-Note that since NaN is considered as a `Float64` in Julia, we have also a promotion to `Float64` in such cases:
+Since NaN is considered as a `Float64` in Julia, we have also a promotion to `Float64` in such cases:
 
 ```julia
 [1f0, NaN]
@@ -272,16 +270,15 @@ ds["var64"][:,:]
 # NaN    20.0  30.0
 ```
 
-#### Precision when converting integers to floats
-
 Promoting an integer to a floating point number can lead to loss of precision. These are the smallest integers that cannot be represented as 32 and 64-bit floating numbers:
 
 ```julia
 Float32(16_777_217) == 16_777_217 # false
 Float64(9_007_199_254_740_993) == 9_007_199_254_740_993 # false
 ```
 
-The use of `missing` as fill value, is thus preferable generally.
+`NaN` should be used for an array of dates, character or strings as it will result in an array with the element type `Any` following julia's promotion rules.
+The use of `missing` as fill value, is thus preferable in the general case.
 
 
 ## Experimental functions