Merge pull request #104 from gaelforget/v0p2p18d

V0p2p18d

docs/src/API.md

@@ -16,7 +16,7 @@ ModelConfig(::Function)
 PlutoConfig
 ```
 
-## Default Methods
+## General Methods
 
 ```@docs
 setup(::ModelConfig)
@@ -25,17 +25,21 @@ launch
 log
 ```
 
+Also provided : [`pathof`](@ref), [`readdir`](@ref), [`show`](@ref), [`clean`](@ref), and [`@ModelRun`](@ref)
+
 ## [Notebook Methods](@id notebook_methods)
 
 The `setup` method for `PlutoConfig` uses `unroll` to pre-process notebook codes.
 
 ```@docs
 setup(::PlutoConfig)
+notebooks.update(::PlutoConfig)
+notebooks.open(::PlutoConfig)
 notebooks.unroll
 notebooks.reroll
 ```
 
-## Other Methods
+## More
 
 ### Simplified API
 
@@ -60,7 +64,6 @@ Convenience functions for notebooks documented in the `JuliaClimate/Notebooks` w
 ```@docs
 notebooks.list
 notebooks.download
-notebooks.open
 ```
 
 ### PkgDevConfig

src/interface.jl

@@ -100,6 +100,14 @@ Returns the run directory path for x ; i.e. joinpath(x.folder,string(x.ID))
 """
 pathof(x::AbstractModelConfig) = joinpath(x.folder,string(x.ID))
 
+
+"""
+ pathof(x::AbstractModelConfig,subfolder::String)
+
+Same as pathof(joinpath(x,subfolder)).
+"""
+pathof(x::AbstractModelConfig,subfolder::String) = joinpath(pathof(x),subfolder)
+
 """
  readdir(x::AbstractModelConfig)
 

src/notebooks.jl

@@ -8,7 +8,9 @@ import ClimateModels: PlutoConfig, setup, git_log_fil, default_ClimateModelSetup
 """
  notebooks.list()
 
-List downloadable notebooks based on the `JuliaClimate/Notebooks` webpage. 
+List downloadable notebooks based on the `JuliaClimate/Notebooks` webpage.
+
+Returns a `DataFrame` with columns _folder_, _file_, and _url_. 
 """
 function list()
  fil=Downloads.download("https://raw.githubusercontent.com/JuliaClimate/Notebooks/master/page/index.md")
@@ -52,28 +54,12 @@ end
 
 Download notebooks/files listed in `nbs` to `path`.
 
-If `nbs.file[i]` is found at `nbs.url[i]` then download it to `path`/`nbs.folder[i]`. 
-
-If a second file is found at `nbs.url[i][1:end-3]*"_module.jl"` then we download it too.
+- If `nbs.file[i]` is found at `nbs.url[i]` then download it to `path`/`nbs.folder[i]`. 
+- If a second file is found at `nbs.url[i][1:end-3]*"_module.jl"` then we download it too.
 
 ```
-using ClimateModels, UUIDs
-path=joinpath(tempdir(),string(UUIDs.uuid4()))
-
 nbs=notebooks.list()
-notebooks.download(path,nbs)
-```
-
-or 
-
-```
-using DataFrames
-url0="https://raw.githubusercontent.com/JuliaClimate/IndividualDisplacements.jl/master/examples/worldwide/"
-
-nbs2=DataFrame( "folder" => ["IndividualDisplacements.jl","IndividualDisplacements.jl"], 
- "file" => ["ECCO_FlowFields.jl","OCCA_FlowFields.jl"], 
- "url" => [url0*"ECCO_FlowFields.jl",url0*"OCCA_FlowFields.jl"])
-notebooks.download(path,nbs2)
+notebooks.download(tempdir(),nbs)
 ```
 """
 function download(path,nbs)
@@ -97,34 +83,27 @@ function download(path,nbs)
 end
 
 """
- open(;notebook_path="",notebook_url="",
- pluto_url="http://localhost:1234/",pluto_options="...")
+ open(MC::PlutoConfig))
 
 Open notebook in web-browser via Pluto. 
 
 **Important note:** this assumes that the Pluto server is already running, e.g. from `Pluto.run()`, at URL `pluto_url` (by default, "http://localhost:1234/", should work on a laptop or desktop).
 
-Examples:
-
 ```
-nbs=notebooks.list()
-notebooks.open(notebook_url=nbs.url[1])
-
-notebooks.open(notebook_path="examples/defaults.jl")
-pluto_url="https://ade.ops.maap-project.org/serverpmohyfxe-ws-jupyter/server-3100/pluto/"
-notebooks.open(notebook_path="examples/defaults.jl",pluto_url=pluto_url)
+notebooks.open(PlutoConfig(model="examples/defaults.jl"))
 ```
 """
-function open(;notebook_path="",notebook_url="",
+function open(MC::PlutoConfig;
  pluto_url="http://localhost:1234/",
+ #pluto_url="https://ade.ops.maap-project.org/serverpmohyfxe-ws-jupyter/server-3100/pluto/"
  pluto_options="require_secret_for_open_links=false,require_secret_for_access=false")
+
  url0=split(pluto_url,"?")[1]
  length(url0)>0 && url0[end]=='/' ? url0=url0[1:end-1] : nothing
 
- if !isempty(notebook_url) && !isempty(url0)
- run(`open $(url0)/open\?url=$(notebook_url)`)
- elseif !isempty(notebook_path) && !isempty(url0)
- run(`open $(url0)/open\?path=$(notebook_path)`)
+ pth0=MC.model
+ if !isempty(url0)
+ run(`open $(url0)/open\?path=$(pth0)`)
  else
  error("unknown pluto_url")
  end
@@ -142,7 +121,7 @@ _Project.toml_, _Manifest.toml_, and _CellOrder.txt_.
 - default `mf` is `PlutoFile[1:end-3]*"_module.jl"` unless `ModuleFile` is specified
 - the `reroll` function can be used to reassemble as a Pluto notebook 
 
-For example:
+Use case example: updating notebook dependencies
 
 ```
 using Pkg
@@ -194,7 +173,7 @@ end
 
 The `reroll` function can be used to reassemble as a Pluto notebook that was previously `unroll`'ed.
 
-See `unroll` documentation for an example. 
+See `unroll` documentation for a use case example.
 """
 function reroll(p,f; PlutoFile="notebook.jl")
 
@@ -225,14 +204,14 @@ function reroll(p,f; PlutoFile="notebook.jl")
 end
 
 """
- setup(MC::PlutoConfig;IncludeManifest=true)
+ setup(MC::PlutoConfig)
 
 - call `default_ClimateModelSetup`
 - call `unroll`
 - add `notebook_launch` to tasks
 
 ```
-MC1=PlutoConfig(model="examples/CMIP6.jl")
+MC1=PlutoConfig(model="examples/defaults.jl")
 setup(MC1)
 build(MC1)
 launch(MC1)
@@ -291,4 +270,31 @@ function notebook_launch(MC::PlutoConfig)
  return tmp[1]
 end
 
+"""
+ update(MC::PlutoConfig)
+
+Update notebook dependencies (via `unroll` & `reroll`) and replace initial notebook file.
+
+```
+update(PlutoConfig(model="examples/defaults.jl"))
+run(PlutoConfig(model="examples/defaults.jl"))
+```
+"""
+function update(MC::PlutoConfig)
+ setup(MC)
+
+ reference_project=Pkg.project().path
+
+ p=joinpath(pathof(MC),"run")
+ Pkg.activate(p)
+ Pkg.update()
+
+ mv(MC.model,MC.model*"_old",force=true)
+ mv(notebooks.reroll(p,"main.jl"),MC.model)
+
+ Pkg.activate(reference_project)
+
+ return MC.model
+end
+
 end