functionality to quickly activate the project you want!!! (#11)

* findproject and quick activate functions

* safety in quick activate

* add tests for quick activate and findproject

* test git=false as well.

* docs for the new functions

Author: Datseris

LICENSE

@@ -47,3 +47,36 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+The function `findproject` uses Julia's Base.current_project function. License:
+
+The Julia language is licensed under the MIT License. The "language" consists
+of the compiler (the contents of src/), most of the standard library (base/),
+and some utilities (most of the rest of the files in this repository).
+For more info see https://julialang.org/license
+
+> Copyright (c) 2009-2018: Jeff Bezanson, Stefan Karpinski, Viral B. Shah,
+> and other contributors:
+>
+> https://github.com/JuliaLang/julia/contributors
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

docs/src/project.md

@@ -5,11 +5,8 @@ Part of the functionality of DrWatson is creating and navigating through a proje
 For this to work, you only need to follow these rules:
 
 1. **Your science project is also a Julia project defined by a `Project.toml` file.**
-2. **You first activate this project environment before running any code.** This can be done in multiple ways:
-   * by doing `Pkg.activate("path/to/project")` programmatically
-   * by using the startup flag `--project path` when starting Julia
-   * by setting the [`JULIA_PROJECT`](https://docs.julialang.org/en/latest/manual/environment-variables/#JULIA_PROJECT-1) environment variable
-3. **You use the functions `scriptdir`, `datadir`, etc. from DrWatson** (see [Navigating the Project](@ref))
+2. **You first activate this project environment before running any code.** See [Activating a Project](@ref) for ways to do this.
+3. **You use the functions `scriptdir`, `datadir`, etc. from DrWatson** (see [Navigating a Project](@ref))
 
 ## Default Project Setup
 
@@ -31,9 +28,9 @@ ShowFile(dirname(pathof(DrWatson))*"/defaults/project_structure.txt") # hide
 ### `src` vs `scripts`
 Seems like `src` and `scripts` folders have pretty similar functionality. However there is a distinction between these two. You can follow these mental rules to know where to put `file.jl`:
 
-1. If upon `include("file.jl")` there is _anything_ being produced, be it data files, plots or even output to the console, then it should be in `scripts`.
-2. If it is functionality used across multiple files or pipelines, it should be in `src`.
-3. `src` should only contain files that define functions or types but not output anything. You can also organize `src` to be a Julia package, or contain multiple Julia packages.
+* If upon `include("file.jl")` there is _anything_ being produced, be it data files, plots or even output to the console, then it should be in `scripts`.
+* If it is functionality used across multiple files or pipelines, it should be in `src`.
+* `src` should only contain files that define functions or types but not output anything. You can also organize `src` to be a Julia package, or contain multiple Julia packages.
 
 ## Initializing a Project
 
@@ -42,7 +39,29 @@ To initialize a project as described in the [Default Project Setup](@ref) sectio
 initialize_project
 ```
 
-## Navigating the Project
+## Activating a Project
+This part of DrWatson's functionality requires you to have your scientific project (and as a consequence, the Julia project) activated.
+This can be done in multiple ways:
+   1. doing `Pkg.activate("path/to/project")` programmatically
+   2. using the startup flag `--project path` when starting Julia
+   3. by setting the [`JULIA_PROJECT`](https://docs.julialang.org/en/latest/manual/environment-variables/#JULIA_PROJECT-1) environment variable
+   4. using the functions [`quickctivate`](@ref) and [`findproject`](@ref) offered by DrWatson.
+
+We highly recommend the fourth approach. Here is how it works: the function [`quickactivate`](@ref) activates a project given some path by recursively searching the path and its parents for a valid `Project.toml` file. Typically you put this function in your script files like so:
+```julia
+using DrWatson # and any other package you use
+quickactivate(@__DIR__)
+# or
+quickactivate(@__DIR__, "Best project in the WORLLDD")
+```
+where the second optional argument can assert if the activated project matches the name you provided, see below for more.
+
+```@docs
+quickactivate
+findproject
+```
+
+## Navigating a Project
 To be able to navigate the project consistently, DrWatson provides the following functions:
 ```julia
 datadir() = projectdir()*"data/"

src/project_setup.jl

@@ -3,6 +3,7 @@
 ##########################################################################################
 export projectdir, datadir, srcdir, plotsdir, scriptdir
 export projectname
+export findproject, quickactivate
 
 """
     projectdir()
@@ -20,6 +21,59 @@ Return the name of the currently active project.
 """
 projectname() = Pkg.REPLMode.promptf()[2:end-7]
 
+"""
+    findproject(path = pwd()) -> project_path
+Recursively search `path` and its parents for a valid Julia project file.
+If it is found return its path, otherwise issue a warning and return
+`nothing`.
+
+The function stops searching if it hits either the home directory or
+the root directory.
+"""
+function findproject(dir::AbstractString = pwd())
+    # look for project file in current dir and parents
+    home = homedir()
+    while true
+        for proj in Base.project_names
+            file = joinpath(dir, proj)
+            Base.isfile_casesensitive(file) && return dir
+        end
+        # bail at home directory
+        dir == home && break
+        # bail at root directory
+        old, dir = dir, dirname(dir)
+        dir == old && break
+    end
+    @warn "Could not find find a project file by recursively checking "*
+    "given `path` and its parents. Returning `nothing` instead."
+    return nothing
+end
+
+"""
+    quickactivate(path [, name::String])
+Activate the project found by [`findproject`](@ref) of the `path`.
+Optionally check if `name` is the same as the activated project's name.
+If it is not, throw an error.
+
+This function is _first_ activating the project and _then_ checking if
+it matches the `name`.
+"""
+function quickactivate(path, name = nothing)
+    projectpath = findproject(path)
+    projectpath === nothing && return nothing
+    Pkg.activate(projectpath)
+    if !(name === nothing) && projectname() != name
+        error(
+        "The activated project did not match asserted name. Current project "*
+        "name is $(projectname()) while the asserted name is $name."
+        )
+    end
+    return nothing
+end
+
+
+
+
 ##########################################################################################
 # Project directory and setup management
 ##########################################################################################
@@ -71,8 +125,7 @@ function initialize_project(path, name = basename(path);
     if git; repo = LibGit2.init(path); end
     git && LibGit2.commit(repo, "Initial commit")
     Pkg.activate(path)
-    # Pkg.add("DrWatson")#Uncomment when the package is released
-    Pkg.add("Pkg")
+    Pkg.add("DrWatson")
 
     # Default folders
     for p in DEFAULT_PATHS

test/project_tests.jl

@@ -8,6 +8,7 @@ name = "lala"
 initialize_project(path)
 
 @test projectname() == path
+@test findproject(@__DIR__) === nothing
 for p in DrWatson.DEFAULT_PATHS
     @test ispath(joinpath(path, p))
 end
@@ -31,8 +32,13 @@ z = read((path*"/Project.toml"), String)
 @test occursin("[\"George\", \"Nick\"]", z)
 
 initialize_project(path, name; force = true, authors = "Sophia", git = false)
+@test !isdir(joinpath(path, ".git"))
 z = read((path*"/Project.toml"), String)
 @test occursin("[\"Sophia\"]", z)
 
+cd(path)
+@test findproject(pwd()) == pwd()
+cd()
+
 rm(path, recursive = true, force = true)
 @test !isdir(path)