auth docs

Author: mortenpi

docs/make.jl

@@ -32,6 +32,19 @@ const DEFAULT_PROJECT_AUTH = mockauth(
 projectauth_setup!() = JuliaHub.__AUTH__[] = DEFAULT_PROJECT_AUTH
 projectauth_teardown!() = JuliaHub.__AUTH__[] = DEFAULT_GLOBAL_MOCK_AUTH
 
+function env_setup!(; project=false)
+    ENV["JULIA_PKG_SERVER"] = "juliahub.com"
+    if project
+        ENV["JULIAHUB_PROJECT_UUID"] = "b1a95ba8-43e6-4eb6-b280-3c5cbe0fa0b9"
+    end
+    return nothing
+end
+function env_teardown!()
+    delete!(ENV, "JULIA_PKG_SERVER")
+    delete!(ENV, "JULIAHUB_PROJECT_UUID")
+    return nothing
+end
+
 # The following setup function is reused in both at-setup blocks, but also in
 # doctestsetup.
 function setup_job_results_file!()

docs/src/guides/authentication.md

@@ -43,6 +43,8 @@ When working with JuliaHub.jl in JuliaHub cloud environment, such as in JuliaHub
 The `JULIA_PKG_SERVER` should always be correctly set up, and the `auth.toml` file will also be present and up-to-date.
 This means that [`authenticate`](@ref) should automatically be able to authenticate your session, and you should never be prompted for interactive authentication.
 
+This also extends to JuliaHub Projects support --- if an IDE has been launched withing the context of a project, the environment will have the `JULIAHUB_PROJECT_UUID` environment set, and the authentication object will be automatically linked to the correct project.
+
 !!! tip "No need to authenticate()"
 
     As in a JuliaHub environment everything is already set up and pointing to the correct server, you do not need to call [`authenticate`](@ref) yourself, nor set up `JULIA_PKG_SERVER`.

src/authentication.jl

@@ -229,6 +229,39 @@ This can be set by passing the optional `project` argument, which works as follo
     When the [`Authentication`](@ref) object is constructed, access to or existence of the specified
     project is not checked. However, if you attempt any project operations with with such an
     authentication object, they will fail and throw an error.
+
+# Examples
+
+If `JULIA_PKG_SERVER` is set, `authenticate()` will pick it up automatically,
+although it can also be overridden by setting the instance hostname explicitly:
+
+```jldoctest; setup = :(Main.env_setup!()), teardown = :(Main.env_teardown!())
+julia> ENV["JULIA_PKG_SERVER"]
+"juliahub.com"
+
+julia> JuliaHub.authenticate()
+JuliaHub.Authentication("https://juliahub.com", "username", *****)
+
+julia> JuliaHub.authenticate("mycompany.juliahub.com")
+JuliaHub.Authentication("https://mycompany.juliahub.com", "username", *****)
+```
+
+If `JULIAHUB_PROJECT_UUID` is set to point to a JuliaHub Project (e.g. in JuliaHub cloud
+environments), it will also get automatically picked up, but can also be overridden:
+
+```jldoctest; setup = :(Main.env_setup!(; project=true)), teardown = :(Main.env_teardown!())
+julia> ENV["JULIAHUB_PROJECT_UUID"]
+"b1a95ba8-43e6-4eb6-b280-3c5cbe0fa0b9"
+
+julia> JuliaHub.authenticate()
+JuliaHub.Authentication("https://juliahub.com", "username", *****; project_id = "b1a95ba8-43e6-4eb6-b280-3c5cbe0fa0b9")
+
+julia> JuliaHub.authenticate(; project = "7ed96f69-a765-4de6-ac00-04a38684ce1c")
+JuliaHub.Authentication("https://juliahub.com", "username", *****; project_id = "7ed96f69-a765-4de6-ac00-04a38684ce1c")
+
+julia> JuliaHub.authenticate(; project = nothing)
+JuliaHub.Authentication("https://juliahub.com", "username", *****)
+```
 """
 function authenticate end