Docs and some API usabilities (#534)

* docs

* fix from review

* fixes

stdlib/Pkg/docs/make.jl

@@ -1,6 +1,8 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-using Documenter, Pkg
+Base.ACTIVE_PROJECT[] = joinpath(@__DIR__, "..")
+using Documenter
+using Pkg
 
 makedocs(
     modules = [Pkg],

stdlib/Pkg/docs/src/index.md

@@ -193,6 +193,9 @@ Since we haven't created our own project yet, we are in the default project, loc
 
 To return to the `julia>` prompt, either press backspace when the input line is empty or press Ctrl+C.
 Help is available by calling `pkg> help`.
+If you are in an environment that does not have access to a REPL you can still use the REPL mode commands using
+the string macro `pkg` available after `using Pkg`. The command `pkg"cmd"` would be equivalent to executing `cmd`
+in the REPL mode.
 
 The documentation here describes using Pkg from the REPL mode. Documentation of using
 the Pkg API (by calling `Pkg.` functions) is in progress of being written.
@@ -831,3 +834,30 @@ Simply clone their project using e.g. `git clone`, `cd` to the project directory
 
 If the project contains a manifest, this will install the packages in the same state that is given by that manifest.
 Otherwise, it will resolve the latest versions of the dependencies compatible with the project.
+
+## References
+
+This section describes the "API mode" of interacting with Pkg.jl which is recommended for non-interactive usage,
+in i.e. scripts. In the REPL mode packages (with associated version, UUID, URL etc) are parsed from strings, 
+for example, `"Package#master"`,`"[email protected]"`, `"www.mypkg.com/MyPkg#my/feature"`. 
+It is possible to use strings as arguments for simple commands in the API mode (like `Pkg.add(["PackageA", "PackageB"])`,
+more complicated commands, that e.g. specify URLs or version range, uses a more structured format over strings.
+This is done by creating an instance of a [`PackageSpec`](@ref) which are passed in to functions.
+
+```@docs
+PackageSpec
+PackageMode
+UpgradeLevel
+Pkg.add
+Pkg.develop
+Pkg.activate
+Pkg.rm
+Pkg.update
+Pkg.test
+Pkg.build
+Pkg.pin
+Pkg.free 
+Pkg.instantiate
+Pkg.resolve
+Pkg.setprotocol!
+```

stdlib/Pkg/src/API.jl

@@ -17,15 +17,25 @@ preview_info() = printstyled("───── Preview mode ─────\n"; c
 
 include("generate.jl")
 
-parse_package(pkg) = Pkg.REPLMode.parse_package(pkg; add_or_develop=true)
+function check_package_name(x::String)
+    if !(occursin(Pkg.REPLMode.name_re, x))
+         cmderror("$x is not a valid packagename")
+    end
+    return PackageSpec(x)
+end
 
 add_or_develop(pkg::Union{String, PackageSpec}; kwargs...) = add_or_develop([pkg]; kwargs...)
-add_or_develop(pkgs::Vector{String}; kwargs...)            = add_or_develop([parse_package(pkg) for pkg in pkgs]; kwargs...)
+add_or_develop(pkgs::Vector{String}; kwargs...)            = add_or_develop([check_package_name(pkg) for pkg in pkgs]; kwargs...)
 add_or_develop(pkgs::Vector{PackageSpec}; kwargs...)       = add_or_develop(Context(), pkgs; kwargs...)
 
 function add_or_develop(ctx::Context, pkgs::Vector{PackageSpec}; mode::Symbol, kwargs...)
     Context!(ctx; kwargs...)
 
+    # All developed packages should go through handle_repos_develop so just give them an empty repo
+    for pkg in pkgs
+        mode == :develop && pkg.repo == nothing && (pkg.repo = Types.GitRepo())
+    end
+
     # if julia is passed as a package the solver gets tricked;
     # this catches the error early on
     any(pkg->(pkg.name == "julia"), pkgs) &&
@@ -55,12 +65,10 @@ end
 
 add(args...; kwargs...) = add_or_develop(args...; mode = :add, kwargs...)
 develop(args...; kwargs...) = add_or_develop(args...; mode = :develop, kwargs...)
-@deprecate checkout develop
-
 
-rm(pkg::Union{String, PackageSpec}; kwargs...)               = rm([pkg]; kwargs...)
-rm(pkgs::Vector{String}; kwargs...)      = rm([PackageSpec(pkg) for pkg in pkgs]; kwargs...)
-rm(pkgs::Vector{PackageSpec}; kwargs...) = rm(Context(), pkgs; kwargs...)
+rm(pkg::Union{String, PackageSpec}; kwargs...) = rm([pkg]; kwargs...)
+rm(pkgs::Vector{String}; kwargs...)            = rm([PackageSpec(pkg) for pkg in pkgs]; kwargs...)
+rm(pkgs::Vector{PackageSpec}; kwargs...)       = rm(Context(), pkgs; kwargs...)
 
 function rm(ctx::Context, pkgs::Vector{PackageSpec}; kwargs...)
     Context!(ctx; kwargs...)
@@ -379,11 +387,11 @@ function _get_deps!(ctx::Context, pkgs::Vector{PackageSpec}, uuids::Vector{UUID}
     return
 end
 
+
 build(pkgs...) = build([PackageSpec(pkg) for pkg in pkgs])
 build(pkg::Array{Union{}, 1}) = build(PackageSpec[])
 build(pkg::PackageSpec) = build([pkg])
 build(pkgs::Vector{PackageSpec}) = build(Context(), pkgs)
-
 function build(ctx::Context, pkgs::Vector{PackageSpec}; kwargs...)
     Context!(ctx; kwargs...)
 
@@ -424,7 +432,7 @@ function clone(url::String, name::String = "")
     if !isempty(name)
         ctx.old_pkg2_clone_name = name
     end
-    develop(ctx, [parse_package(url)])
+    develop(ctx, [Pkg.REPLMode.parse_package(url; add_or_develop=true)])
 end
 
 function dir(pkg::String, paths::String...)
@@ -541,6 +549,13 @@ function instantiate(ctx::Context; manifest::Union{Bool, Nothing}=nothing, kwarg
     Operations.build_versions(ctx, union(new_apply, new_git))
 end
 
+
+status(mode=PKGMODE_PROJECT) = status(Context(), mode)
+function status(ctx::Context, mode=PKGMODE_PROJECT)
+    Pkg.Display.status(ctx, mode)
+    return
+end
+
 function activate(path::Union{String,Nothing}=nothing)
     Base.ACTIVE_PROJECT[] = Base.load_path_expand(path)
 end