docs improvments

docs/src/index.md

@@ -8,21 +8,56 @@ RasterDataSources
 
 RasterDataSources.jl only exports a single function, `getraster`.
 
-```@autodocs
-Modules = [RasterDataSources]
-Private = false
-Order = [:function]
+```@docs
+getraster
 ```
 
+Specific implementations are included with each source, below.
+
+
 # Data sources
 
 ```@docs
 RasterDataSources.RasterDataSource
+```
+
+## ALWB
+
+```@docs
 ALWB
+getraster(T::Type{<:ALWB}, layers::Union{Tuple,Symbol}; date)
+```
+
+## AWAP
+
+```@docs
 AWAP
+getraster(T::Type{AWAP}, layer::Union{Tuple,Symbol}; date)
+```
+
+## CHELSA
+
+```@docs
 CHELSA
+getraster(T::Type{CHELSA{BioClim}}, layer::Union{Tuple,Int,Symbol})
+getraster(T::Type{<:CHELSA{<:Future{Climate}}}, layers::Union{Tuple,Symbol}; date, month)
+```
+
+## EarthEnv
+
+```@docs
 EarthEnv
+getraster(T::Type{EarthEnv{HabitatHeterogeneity}}, layers::Union{Tuple,Symbol}; res)
+getraster(T::Type{EarthEnv{LandCover}}, layers::Union{Tuple,Int,Symbol}; res)
+```
+
+## WorldClim
+
+```@docs
 WorldClim
+getraster(T::Type{WorldClim{BioClim}}, layers::Union{Tuple,Int,Symbol}; res)
+getraster(T::Type{WorldClim{Weather}}, layers::Union{Tuple,Symbol}; date)
+getraster(T::Type{WorldClim{Climate}}, layers::Union{Tuple,Symbol}; month, res)
 ```
 
 # Datasets
@@ -34,11 +69,24 @@ Climate
 Weather
 LandCover
 HabitatHeterogeneity
+Future
+```
+
+# Models, phases and scenarios for [`Future`](@ref) data.
+
+```@docs
+RasterDataSources.ClimateModel
+RasterDataSources.CMIPphase 
+CMIP5
+CMIP6
+RasterDataSources.ClimateScenario 
+RasterDataSources.RepresentativeConcentrationPathway
+RasterDataSources.SharedSocioeconomicPathway
 ```
 
 # Other
 
-```julia
+```@docs
 Values
 Deciles
 ```

src/alwb/alwb.jl

@@ -17,6 +17,7 @@ Get the dataset in relative deciles.
 """
 struct Deciles <: DataMode end
 
+# Docs below
 struct ALWB{M<:DataMode,D<:Union{Day,Month,Year}} <: RasterDataSource end
 
 layers(::Type{<:ALWB}) = (
@@ -46,6 +47,8 @@ The available layers are: `$(layers(ALWB))`, available in daily, monthly and
 annual resolutions, and as `Values` or relative `Deciles`.
 
 `getraster` for `ALWB` must use a `date` keyword to specify the date to download.
+
+See the [`getraster`](@ref) docs for implementation details.
 """ ALWB
 
 # http://www.bom.gov.au/jsp/awra/thredds/fileServer/AWRACMS/values/day/rain_day_2017.nc

src/chelsa/future.jl

@@ -13,7 +13,9 @@ const CHELSAKEY = (prec="pr", temp="tas", tmin="tasmin", tmax="tasmax", bio="bio
 """
     getraster(T::Type{CHELSA{Future{BioClim}}}, [layer]; date) => String
 
-Download CHELSA BioClim data, choosing layers from: `$(layers(CHELSA{BioClim}))`.
+Download CHELSA [`BioClim`](@ref) data, choosing layers from: `$(layers(CHELSA{BioClim}))`.
+
+See the docs for [`Future`](@ref) for model choices.
 
 Without a layer argument, all layers will be downloaded, and a `NamedTuple` of paths 
 returned.
@@ -33,7 +35,9 @@ end
 """
     getraster(T::Type{CHELSA{Future{Climate}}}, [layer]; date, month) => String
 
-Download CHELSA BioClim data, choosing layers from: `$(layers(CHELSA{BioClim}))`.
+Download CHELSA [`Climate`](@ref) data, choosing layers from: `$(layers(CHELSA{BioClim}))`.
+
+See the docs for [`Future`](@ref) for model choices.
 
 Without a layer argument, all layers will be downloaded, and a `NamedTuple` of paths returned.
 

src/chelsa/shared.jl

@@ -1,10 +1,11 @@
 """
-    CHELSA{BioClim} <: RasterDataSource
+    CHELSA{Union{BioClim,<:Future}} <: RasterDataSource
 
-Data from CHELSA, currently implements thet current and future bioclim
-variables.
+Data from CHELSA, currently implements the current `BioClim` and
+`Future{BioClim}` variables, and `Future{Climate}`.
 
-See: [chelsa-climate.org](https://chelsa-climate.org/)
+See: [chelsa-climate.org](https://chelsa-climate.org/) for the dataset,
+and the [`getraster`](@ref) docs for implementation details.
 """
 struct CHELSA{X} <: RasterDataSource end
 

src/earthenv/landcover.jl

@@ -28,8 +28,8 @@ Download [`EarthEnv`](@ref) landcover data.
 # Arguments
 
 - `layer`: `Integer` or tuple/range of `Integer` from `$(layers(EarthEnv{LandCover}))`,
-    or `$(layerkeys(EarthEnv{LandCover}))`. Without a `layer` argument, all layers will
-    be downloaded, and a `NamedTuple` of paths returned.
+    or `Symbol`s from `$(layerkeys(EarthEnv{LandCover}))`. Without a `layer` argument,
+    all layers will be downloaded, and a `NamedTuple` of paths returned.
 
 `LandCover` may also be `LandCover{:DISCover} to download the dataset that integrates the DISCover model.
 

src/types.jl

@@ -15,8 +15,16 @@ abstract type RasterDataSet end
 """
     BioClim <: RasterDataSet
 
-BioClim datasets. Usually containing layers from 1:19. They do not usually use
-`month` or `date` keywords, but may use `date` in past/future scenarios. 
+BioClim datasets. Usually containing layers from `1:19`. 
+These can also be accessed with `:bioX`, e.g. `:bio5`.
+
+They do not usually use `month` or `date` keywords, but may use
+`date` in past/future scenarios. 
+
+Currently implemented for WorldClim and CHELSA as `WorldClim{BioClim}`,
+`CHELSA{BioClim}` and `CHELSA{Future{BioClim, args..}}`.
+
+See the [`getraster`](@ref) docs for implementation details.
 """
 struct BioClim <: RasterDataSet end
 
@@ -61,7 +69,12 @@ bioclim_int(k::Symbol) = bioclim_lookup[bioclim_key(k)]
     Climate <: RasterDataSet
 
 Climate datasets. These are usually months of the year, not specific dates,
-and use a `month` keyword in `getraster`. They may also use `date` in past/future scenarios.
+and use a `month` keyword in `getraster`. They also use `date` in past/future scenarios.
+
+Currently implemented for WorldClim and CHELSA as `WorldClim{Climate}`,
+`CHELSA{Climate}` and `CHELSA{Future{Climate, args..}}`.
+
+See the [`getraster`](@ref) docs for implementation details.
 """
 struct Climate <: RasterDataSet end
 
@@ -72,20 +85,33 @@ months(::Type{Climate}) = ntuple(identity, Val{12})
 
 Weather datasets. These are usually large time-series of specific dates,
 and use a `date` keyword in `getraster`.
+
+Currently implemented for WorldClim and CHELSA as `WorldClim{Weather}`,
+and `CHELSA{Weather}`
+
+See the [`getraster`](@ref) docs for implementation details.
 """
 struct Weather <: RasterDataSet end
 
 """
     LandCover <: RasterDataSet
 
 Land-cover datasets.
+
+Currently implemented for EarthEnv as `EarchEnv{LandCover}`.
+
+See the [`getraster`](@ref) docs for implementation details.
 """
 struct LandCover{X} <: RasterDataSet end
 
 """
     HabitatHeterogeneity <: RasterDataSet
 
 Habitat heterogeneity datasets.
+
+Currently implemented for EarchEnv as `EarchEnv{HabitatHeterogeneity}`.
+
+See the [`getraster`](@ref) docs for implementation details.
 """
 struct HabitatHeterogeneity <: RasterDataSet end
 
@@ -141,6 +167,14 @@ struct MRIESM2 <: ClimateModel end
 struct UKESM <: ClimateModel end
 struct MPIESMHR <: ClimateModel end
 
+"""
+    CMIPphase 
+
+Abstract supertype for phases of the CMIP,
+the Coupled Model Intercomparison Project.
+
+Subtypes are `CMIP5` and `CMIP6`.
+"""
 abstract type CMIPphase end
 
 """
@@ -157,12 +191,21 @@ The Coupled Model Intercomparison Project, Phase 6.
 """
 struct CMIP6 <: CMIPphase end
 
+"""
+    ClimateScenario 
+
+Abstract supertype for scenarios used in [`CMIPphase`](@ref) models.
+"""
+abstract type ClimateScenario end
+
 """
     RepresentativeConcentrationPathway
 
-Abstract supertype for Representative Concentration Pathways (RCPs)
+Abstract supertype for Representative Concentration Pathways (RCPs) for [`CMIP5`](@ref).
+
+Subtypes are: `RCP26`, `RCP45`, `RCP60`, `RCP85`
 """
-abstract type RepresentativeConcentrationPathway end
+abstract type RepresentativeConcentrationPathway <: ClimateScenario end
 
 struct RCP26 <: RepresentativeConcentrationPathway end
 struct RCP45 <: RepresentativeConcentrationPathway end
@@ -172,22 +215,69 @@ struct RCP85 <: RepresentativeConcentrationPathway end
 """
     SharedSocioeconomicPathway
 
-Abstract supertype for Shared Socio-economic Pathways (SSPs)
+Abstract supertype for Shared Socio-economic Pathways (SSPs) for [`CMIP6`](@ref).
+
+Subtypes are: `SSP126`, `SSP245`, SSP370`, SSP585`
 """
-abstract type SharedSocioeconomicPathway end
+abstract type SharedSocioeconomicPathway <: ClimateScenario end
 
 struct SSP126 <: SharedSocioeconomicPathway end
 struct SSP245 <: SharedSocioeconomicPathway end
 struct SSP370 <: SharedSocioeconomicPathway end
 struct SSP585 <: SharedSocioeconomicPathway end
 
-# A ClimateScenario can be a RCP or a SSP
-const ClimateScenario = Union{RepresentativeConcentrationPathway, SharedSocioeconomicPathway}
-
 """
-    Future{D<:RasterDataSet,M<:ClimateModel,S<:ClimateScenario}
+    Future{<:RasterDataSet,<:CMIPphase,<:ClimateModel,<:ClimateScenario}
+
+Future climate datasets specified with a dataset, phase, model, and scenario.
+
+## Type Parameters
+
+#### `RasterDataSet`
+
+Currently [`BioClim`](@ref) and [`Climate`](@ref) are implemented
+for the [`CHELSA`](@ref) data source.
+
+#### `CMIPphase`
+
+Can be either [`CMIP5`](@ref) or [`CMIP6`](@ref).
+
+#### `ClimateModel`
+
+Climate models can be chosen from: 
+
+`ACCESS1`, `BNUESM`, `CCSM4`, `CESM1BGC`, `CESM1CAM5`, `CMCCCMS`, `CMCCCM`,
+`CNRMCM5`, `CSIROMk3`, `CanESM2`, `FGOALS`, `FIOESM`, `GFDLCM3`, `GFDLESM2G`,
+`GFDLESM2M`, `GISSE2HCC`, `GISSE2H`, `GISSE2RCC`, `GISSE2R`, `HadGEM2AO`,
+`HadGEM2CC`, `IPSLCM5ALR`, `IPSLCM5AMR`, `MIROCESMCHEM`, `MIROCESM`, `MIROC5`,
+`MPIESMLR`, `MPIESMMR`, `MRICGCM3`, `MRIESM1`, `NorESM1M`, `BCCCSM1`, `Inmcm4`,
+`BCCCSM2MR`, `CNRMCM61`, `CNRMESM21`, `CanESM5`, `GFDLESM4`, `IPSLCM6ALR`,
+`MIROCES2L`, `MIROC6`, `MRIESM2`, `UKESM`, `MPIESMHR`
+
+Note: not all of these will be available for both `CMIP5` and `CMIP6`.
+
+#### `ClimateScenario`
+
+CMIP5 Climate scenarios are all [`RepresentativeConcentrationPathway`](@ref)
+and can be chosen from: `RCP26`, `RCP45`, `RCP60`, `RCP85`
+
+CMIP6 Climate scenarios are all [`SharedSocioeconomicPathway`](@ref) and
+can be chosen from: `SSP126`, `SSP245`, SSP370`, SSP585`
+
+## Example
+
+```jldoctest future
+using RasterDataSources
+dataset = Future{BioClim, CMIP5, BNUESM, RCP45}
+# output
+Future{BioClim, CMIP5, BNUESM, RCP45}
+```
+Currently `Future` is only implented for `CHELSA`
+
+```jldoctest future
+datasource = CHELSA{Future{BioClim, CMIP5, BNUESM, RCP45}}
+```
 
-Future climate dataset: specified by a dataset, model, and scenario.
 """
 struct Future{D<:RasterDataSet,C<:CMIPphase,M<:ClimateModel,S<:ClimateScenario} end
 

src/worldclim/climate.jl

@@ -10,8 +10,7 @@ Download [`WorldClim`](@ref) [`Climate`](@ref) data.
     Without a `layer` argument, all layers will be downloaded, and a `NamedTuple` of paths returned.
 
 # Keywords
-- `month`: `Integer` or `AbstractArray` of `Integer`. By default all months are downloaded,
-    but can be chosen from `1:12`.
+- `month`: `Integer` or `AbstractArray` of `Integer`. Chosen from `1:12`.
 - `res`: `String` chosen from $(resolutions(WorldClim{Climate})), "10m" by default.
 
 Returns the filepath/s of the downloaded or pre-existing files.