From 3c2fee34ad8f668f5cf9001d6b7d605965ec28bb Mon Sep 17 00:00:00 2001 From: Peter Amstutz Date: Tue, 1 Nov 2016 10:20:14 -0400 Subject: [PATCH] 10346: Document SDK examples uniformly --- doc/_config.yml | 9 ++- doc/_layouts/default.html.liquid | 2 +- .../install-prerequisites.html.textile.liquid | 4 +- doc/sdk/cli/install.html.textile.liquid | 1 - doc/sdk/go/example.html.textile.liquid | 43 +++++++++- doc/sdk/go/index.html.textile.liquid | 13 +-- doc/sdk/index.html.textile.liquid | 4 +- doc/sdk/java/example.html.textile.liquid | 78 ++++++++++++++++++ doc/sdk/java/index.html.textile.liquid | 11 ++- doc/sdk/perl/example.html.textile.liquid | 81 +++++++++++++++++++ doc/sdk/perl/index.html.textile.liquid | 59 +------------- doc/sdk/python/example.html.textile.liquid | 23 ++++-- doc/sdk/python/sdk-python.html.textile.liquid | 3 +- doc/sdk/ruby/example.html.textile.liquid | 75 +++++++++++++++++ doc/sdk/ruby/index.html.textile.liquid | 74 +---------------- 15 files changed, 313 insertions(+), 167 deletions(-) create mode 100644 doc/sdk/java/example.html.textile.liquid create mode 100644 doc/sdk/perl/example.html.textile.liquid create mode 100644 doc/sdk/ruby/example.html.textile.liquid diff --git a/doc/_config.yml b/doc/_config.yml index d77b39dff5..4f9e200ca9 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -83,8 +83,8 @@ navbar: - sdk/python/crunch-utility-libraries.html.textile.liquid - sdk/python/events.html.textile.liquid - CLI: - - sdk/cli/index.html.textile.liquid - sdk/cli/install.html.textile.liquid + - sdk/cli/index.html.textile.liquid - sdk/cli/reference.html.textile.liquid - sdk/cli/subcommands.html.textile.liquid - Go: @@ -92,10 +92,13 @@ navbar: - sdk/go/example.html.textile.liquid - Perl: - sdk/perl/index.html.textile.liquid + - sdk/perl/example.html.textile.liquid - Ruby: - sdk/ruby/index.html.textile.liquid + - sdk/ruby/example.html.textile.liquid - Java: - sdk/java/index.html.textile.liquid + - sdk/java/example.html.textile.liquid api: - Concepts: - api/index.html.textile.liquid @@ -153,12 +156,12 @@ navbar: - install/configure-azure-blob-storage.html.textile.liquid - install/install-keepproxy.html.textile.liquid - install/install-keep-web.html.textile.liquid - - Install Crunch v2 on SLURM: + - Containers API support on SLURM: - install/crunch2-slurm/install-prerequisites.html.textile.liquid - install/crunch2-slurm/install-compute-node.html.textile.liquid - install/crunch2-slurm/install-dispatch.html.textile.liquid - install/crunch2-slurm/install-test.html.textile.liquid - - Install Crunch v1: + - Jobs API support (deprecated): - install/install-crunch-dispatch.html.textile.liquid - install/install-compute-node.html.textile.liquid - Helpful hints: diff --git a/doc/_layouts/default.html.liquid b/doc/_layouts/default.html.liquid index ed232c6773..4c4e2542fa 100644 --- a/doc/_layouts/default.html.liquid +++ b/doc/_layouts/default.html.liquid @@ -2,7 +2,7 @@ - {% unless page.title == "Arvados | Documentation" %} Arvados | Documentation | {% endunless %}{{ page.title }} + {% unless page.title == "Arvados | Documentation" %} Arvados {% if page.navmenu %}| {{ page.navmenu }} {% endif %} | {% endunless %}{{ page.title }} diff --git a/doc/install/crunch2-slurm/install-prerequisites.html.textile.liquid b/doc/install/crunch2-slurm/install-prerequisites.html.textile.liquid index c4dc92940b..26c7dde361 100644 --- a/doc/install/crunch2-slurm/install-prerequisites.html.textile.liquid +++ b/doc/install/crunch2-slurm/install-prerequisites.html.textile.liquid @@ -1,9 +1,9 @@ --- layout: default navsection: installguide -title: Crunch v2 SLURM prerequisites +title: Containers API SLURM prerequisites ... -Crunch v2 containers can be dispatched to a SLURM cluster. The dispatcher sends work to the cluster using SLURM's @sbatch@ command, so it works in a variety of SLURM configurations. +Containers can be dispatched to a SLURM cluster. The dispatcher sends work to the cluster using SLURM's @sbatch@ command, so it works in a variety of SLURM configurations. In order to run containers, you must run the dispatcher as a user that has permission to set up FUSE mounts and run Docker containers on each compute node. This install guide refers to this user as the @crunch@ user. We recommend you create this user on each compute node with the same UID and GID, and add it to the @fuse@ and @docker@ system groups to grant it the necessary permissions. However, you can run the dispatcher under any account with sufficient permissions across the cluster. diff --git a/doc/sdk/cli/install.html.textile.liquid b/doc/sdk/cli/install.html.textile.liquid index 8cde514f68..4776a97895 100644 --- a/doc/sdk/cli/install.html.textile.liquid +++ b/doc/sdk/cli/install.html.textile.liquid @@ -3,7 +3,6 @@ layout: default navsection: sdk navmenu: CLI title: "Installation" - ... Arvados CLI tools are written in Ruby and Python. To use the @arv@ command, you can either install the @arvados-cli@ gem via RubyGems or build and install the package from source. The @arv@ command also relies on other Arvados tools. To get those, install the @arvados-python-client@ and @arvados-cwl-runner@ packages, either from PyPI or source. diff --git a/doc/sdk/go/example.html.textile.liquid b/doc/sdk/go/example.html.textile.liquid index 903d367733..d8fccae08e 100644 --- a/doc/sdk/go/example.html.textile.liquid +++ b/doc/sdk/go/example.html.textile.liquid @@ -2,34 +2,71 @@ layout: default navsection: sdk navmenu: Python -title: Python SDK examples +title: Examples ... +h2. Initialize SDK + +
+import (
+  "git.curoverse.com/arvados.git/sdk/go/arvados"
+  "git.curoverse.com/arvados.git/sdk/go/arvadosclient"
+}
+
+func main() {
+  arv, err := arvadosclient.MakeArvadosClient()
+  if err != nil {
+    log.Fatalf("Error setting up arvados client %s", err.Error())
+  }
+}
+
+ h2. create 
   var collection arvados.Collection
-  err := api.Create("collection", Dict{"collection": Dict{"name": "create example"}}, &collection)
+  err := api.Create("collections", Dict{"collection": Dict{"name": "create example"}}, &collection)
h2. delete 
   var collection arvados.Collection
-  err := api.Delete("collection", "", Dict{"collection": Dict{"name": "create example"}}, &collection)
+  err := api.Delete("collections", "aaaaa-bbbbb-ccccccccccccccc", Dict{}, &collection)
h2. get 
+  var collection arvados.Collection
+  err := api.Get("collections", "aaaaa-bbbbb-ccccccccccccccc", Dict{}, &collection)
h2. list 
+  var collection arvados.Collection
+  err := api.List("collections", Dict{}, &collection)
h2. update 
+  var collection arvados.Collection
+  err := api.Update("collections", "aaaaa-bbbbb-ccccccccccccccc", Dict{"collection": Dict{"name": "update example"}}, &collection)
+
+ +h2. Get current user + +
+  var user arvados.User
+  err := api.Get("users", "current", Dict{}, &user)
+ +h2. Example program + +You can save this source as a .go file and run it: + +{% code 'example_sdk_go' as go %} + +A few more usage examples can be found in the "services/keepproxy":https://dev.arvados.org/projects/arvados/repository/revisions/master/show/services/keepproxy and "sdk/go/keepclient":https://dev.arvados.org/projects/arvados/repository/revisions/master/show/sdk/go/keepclient directories in the arvados source tree. diff --git a/doc/sdk/go/index.html.textile.liquid b/doc/sdk/go/index.html.textile.liquid index 24873318da..f18320a39d 100644 --- a/doc/sdk/go/index.html.textile.liquid +++ b/doc/sdk/go/index.html.textile.liquid @@ -2,24 +2,15 @@ layout: default navsection: sdk navmenu: Go -title: "Go SDK" - +title: "Installation" ... The Go ("Golang":http://golang.org) SDK provides a generic set of wrappers so you can make API calls easily. h3. Installation -You don't need to install anything. Just import the client like this. The go tools will fetch the relevant code and dependencies for you. +Use @go get git.curoverse.com/arvados.git/sdk/go/arvadosclient@. The go tools will fetch the relevant code and dependencies for you. {% code 'example_sdk_go_imports' as go %} If you need pre-release client code, you can use the latest version from the repo by following "these instructions.":https://dev.arvados.org/projects/arvados/wiki/Go#Using-Go-with-Arvados - -h3. Example - -You can save this source as a .go file and run it: - -{% code 'example_sdk_go' as go %} - -A few more usage examples can be found in the "services/keepproxy":https://dev.arvados.org/projects/arvados/repository/revisions/master/show/services/keepproxy and "sdk/go/keepclient":https://dev.arvados.org/projects/arvados/repository/revisions/master/show/sdk/go/keepclient directories in the arvados source tree. diff --git a/doc/sdk/index.html.textile.liquid b/doc/sdk/index.html.textile.liquid index e440e6b8c6..990f09cdec 100644 --- a/doc/sdk/index.html.textile.liquid +++ b/doc/sdk/index.html.textile.liquid @@ -1,13 +1,13 @@ --- layout: default navsection: sdk -title: "Arvados SDK Reference" +title: "SDK Reference" ... This section documents language bindings for the "Arvados API":{{site.baseurl}}/api and Keep that are available for various programming languages. Not all features are available in every SDK. The most complete SDK is the Python SDK. Note that this section only gives a high level overview of each SDK. Consult the "Arvados API":{{site.baseurl}}/api section for detailed documentation about Arvados API calls available on each resource. * "Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html -* "Command line SDK":{{site.baseurl}}/sdk/cli/index.html ("arv") +* "Command line SDK":{{site.baseurl}}/sdk/cli/install.html ("arv") * "Go SDK":{{site.baseurl}}/sdk/go/index.html * "Perl SDK":{{site.baseurl}}/sdk/perl/index.html * "Ruby SDK":{{site.baseurl}}/sdk/ruby/index.html diff --git a/doc/sdk/java/example.html.textile.liquid b/doc/sdk/java/example.html.textile.liquid new file mode 100644 index 0000000000..9ff848b94e --- /dev/null +++ b/doc/sdk/java/example.html.textile.liquid @@ -0,0 +1,78 @@ +--- +layout: default +navsection: sdk +navmenu: Java +title: "Examples" +... + +h2. Initialize SDK + +
+import org.arvados.sdk.Arvados;
+
+ +
+    String apiName = "arvados";
+    String apiVersion = "v1";
+
+    Arvados arv = new Arvados(apiName, apiVersion);
+
+ +h2. create + +
+    Map collection = new HashMap();
+    collection.put("name", "create example");
+
+    Map params = new HashMap();
+    params.put("collection", collection);
+    Map response = arv.call("collections", "create", params);
+
+ +h2. delete + +
+    Map params = new HashMap();
+    params.put("uuid", uuid);
+    Map response = arv.call("collections", "delete", params);
+
+ +h2. get + +
+    params = new HashMap();
+    params.put("uuid", userUuid);
+    Map response = arv.call("users", "get", params);
+
+ +h2. list + +
+    Map params = new HashMap();
+    Map response = arv.call("users", "list", params);
+
+    // get uuid of the first user from the response
+    List items = (List)response.get("items");
+
+    Map firstUser = (Map)items.get(0);
+    String userUuid = (String)firstUser.get("uuid");
+
+ +h2. update + +
+    Map collection = new HashMap();
+    collection.put("name", "update example");
+
+    Map params = new HashMap();
+    params.put("uuid", uuid);
+    params.put("collection", collection);
+    Map response = arv.call("collections", "update", params);
+
+ +h2. Get current user + +
+    Map params = new HashMap();
+    Map response = arv.call("users", "current", params);
+
diff --git a/doc/sdk/java/index.html.textile.liquid b/doc/sdk/java/index.html.textile.liquid index 48f72d3a7d..27984b2fe4 100644 --- a/doc/sdk/java/index.html.textile.liquid +++ b/doc/sdk/java/index.html.textile.liquid @@ -2,8 +2,7 @@ layout: default navsection: sdk navmenu: Java -title: "Java SDK" - +title: "Installation" ... The Java SDK provides a generic set of wrappers so you can make API calls in java. @@ -11,10 +10,10 @@ The Java SDK provides a generic set of wrappers so you can make API calls in jav h3. Introdution * The Java SDK requires Java 6 or later - + * The Java SDK is implemented as a maven project. Hence, you would need a working maven environment to be able to build the source code. If you do not have maven setup, -you may find the "Maven in 5 Minutes":http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html link useful. +you may find the "Maven in 5 Minutes":http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html link useful. * In this document $ARVADOS_HOME is used to refer to the directory where arvados code is cloned in your system. For ex: $ARVADOS_HOME = $HOME/arvados @@ -38,7 +37,7 @@ ARVADOS_API_HOST_INSECURE: Set this to true if you are using self-signed * Please see "api-tokens":{{site.baseurl}}/user/reference/api-tokens.html for full details. - + h3. Building the Arvados SDK @@ -124,7 +123,7 @@ The local repository is usually located in your home directory at diff --git a/doc/sdk/perl/example.html.textile.liquid b/doc/sdk/perl/example.html.textile.liquid new file mode 100644 index 0000000000..980129cf13 --- /dev/null +++ b/doc/sdk/perl/example.html.textile.liquid @@ -0,0 +1,81 @@ +--- +layout: default +navsection: sdk +navmenu: Perl +title: "Examples" +... + +h2. Initialize SDK + +Set up an API client user agent: + + +

+use Arvados;
+my $arv = Arvados->new('apiVersion' => 'v1');
+
+ + +The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version. + +h2. create + +Create an object: + + +
my $test_link = $arv->{'links'}->{'create'}->execute('link' => { 'link_class' => 'test', 'name' => 'test' });
+
+ + +h2. delete + + +
my $some_user = $arv->{'collections'}->{'get'}->execute('uuid' => $collection_uuid);
+
+ + +h2. get + +Retrieve an object by ID: + + +
my $some_user = $arv->{'users'}->{'get'}->execute('uuid' => $current_user_uuid);
+
+ + +Get the UUID of an object that was retrieved using the SDK: + + +
my $current_user_uuid = $current_user->{'uuid'}
+
+ + +h2. list + +Get a list of objects: + + +
my $repos = $arv->{'repositories'}->{'list'}->execute;
+print ("UUID of first repo returned is ", $repos->{'items'}->[0], "\n");
+
+ + +h2. update + +Update an object: + + +
my $test_link = $arv->{'links'}->{'update'}->execute(
+        'uuid' => $test_link->{'uuid'},
+        'link' => { 'properties' => { 'foo' => 'bar' } });
+
+ + +h2. Get current user + +Get the User object for the current user: + + +
my $current_user = $arv->{'users'}->{'current'}->execute;
+
+ diff --git a/doc/sdk/perl/index.html.textile.liquid b/doc/sdk/perl/index.html.textile.liquid index e28d02011b..407008d1f7 100644 --- a/doc/sdk/perl/index.html.textile.liquid +++ b/doc/sdk/perl/index.html.textile.liquid @@ -2,8 +2,7 @@ layout: default navsection: sdk navmenu: Perl -title: "Perl SDK" - +title: "Installation" ... The Perl SDK provides a generic set of wrappers so you can make API calls easily. @@ -63,59 +62,3 @@ EOF arvados.v1.users.current.full_name = 'Your Name' - -h3. Examples - -Set up an API client user agent: - - -
my $arv = Arvados->new('apiVersion' => 'v1');
-
- - -Get the User object for the current user: - - -
my $current_user = $arv->{'users'}->{'current'}->execute;
-
- - -Get the UUID of an object that was retrieved using the SDK: - - -
my $current_user_uuid = $current_user->{'uuid'}
-
- - -Retrieve an object by ID: - - -
my $some_user = $arv->{'users'}->{'get'}->execute('uuid' => $current_user_uuid);
-
- - -Create an object: - - -
my $test_link = $arv->{'links'}->{'create'}->execute('link' => { 'link_class' => 'test', 'name' => 'test' });
-
- - -Update an object: - - -
my $test_link = $arv->{'links'}->{'update'}->execute(
-        'uuid' => $test_link->{'uuid'},
-        'link' => { 'properties' => { 'foo' => 'bar' } });
-
- - -Get a list of objects: - - -
my $repos = $arv->{'repositories'}->{'list'}->execute;
-print ("UUID of first repo returned is ", $repos->{'items'}->[0], "\n");
-
- - -The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version. diff --git a/doc/sdk/python/example.html.textile.liquid b/doc/sdk/python/example.html.textile.liquid index 7ae5e58f8a..fe24dba582 100644 --- a/doc/sdk/python/example.html.textile.liquid +++ b/doc/sdk/python/example.html.textile.liquid @@ -2,9 +2,16 @@ layout: default navsection: sdk navmenu: Python -title: Python SDK examples +title: Examples ... +h2. Initialize SDK + +
+import arvados
+api = arvados.api("v1")
+
+ h2. create 
@@ -14,23 +21,29 @@ result = api.collection().create(body={"collection": {"name": "create example"}}
 h2. delete
 
 
-result = api.collection().delete(uuid="aaaaa-bbbbb-ccccccccccccccc").execute()
+result = api.collections().delete(uuid="aaaaa-bbbbb-ccccccccccccccc").execute()
 

 
 h2. get
 
 
-result = api.collection().get(uuid="aaaaa-bbbbb-ccccccccccccccc").execute()
+result = api.collections().get(uuid="aaaaa-bbbbb-ccccccccccccccc").execute()
 

 
 h2. list
 
 
-result = api.collection().list(filters=[["uuid", "=", "aaaaa-bbbbb-ccccccccccccccc"]]).execute()
+result = api.collections().list(filters=[["uuid", "=", "aaaaa-bbbbb-ccccccccccccccc"]]).execute()
 

 
 h2. update
 
 
-result = api.collection().update(uuid="aaaaa-bbbbb-ccccccccccccccc", body={"collection": {"name": "update example"}}).execute()
+result = api.collections().update(uuid="aaaaa-bbbbb-ccccccccccccccc", body={"collection": {"name": "update example"}}).execute()
+

+
+h2. Get current user
+
+
+result = api.users().current().execute()
 

diff --git a/doc/sdk/python/sdk-python.html.textile.liquid b/doc/sdk/python/sdk-python.html.textile.liquid
index 0b0f77d377..e9b560a965 100644
--- a/doc/sdk/python/sdk-python.html.textile.liquid
+++ b/doc/sdk/python/sdk-python.html.textile.liquid
@@ -2,8 +2,7 @@
 layout: default
 navsection: sdk
 navmenu: Python
-title: "Python SDK"
-
+title: "Installation"
 ...
 
 The Python SDK provides access from Python to the Arvados API and Keep.  It also includes a number of command line tools for using and administering Arvados and Keep, and some conveniences for use in Crunch scripts; see "Crunch utility libraries":crunch-utility-libraries.html for details.
diff --git a/doc/sdk/ruby/example.html.textile.liquid b/doc/sdk/ruby/example.html.textile.liquid
new file mode 100644
index 0000000000..b95b1fc44e
--- /dev/null
+++ b/doc/sdk/ruby/example.html.textile.liquid
@@ -0,0 +1,75 @@
+---
+layout: default
+navsection: sdk
+navmenu: Python
+title: Examples
+...
+
+h2.  Initialize SDK
+
+Import the module and set up an API client user agent:
+
+
+require 'arvados'
+arv = Arvados.new(apiVersion: 'v1')
+

+
+The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version.
+
+h2. create
+
+Create an object:
+
+
+new_link = arv.link.create(link: {link_class: 'test', name: 'test'})
+

+
+h2. delete
+
+Delete an object:
+
+
+arv.link.delete(uuid: new_link[:uuid])
+

+
+h2. get
+
+Retrieve an object by ID:
+
+
+some_user = arv.user.get(uuid: current_user_uuid)
+

+
+1h2. list
+
+Get a list of objects:
+
+
+repos = arv.repository.list
+first_repo = repos[:items][0]
+puts "UUID of first repo returned is #{first_repo[:uuid]}"
+UUID of first repo returned is qr1hi-s0uqq-b1bnybpx3u5temz
+

+
+h2. update
+
+Update an object:
+
+
+updated_link = arv.link.update(uuid: new_link[:uuid],
+                               link: {properties: {foo: 'bar'}})
+

+
+h2. Get current user
+
+Get the User object for the current user:
+
+
+current_user = arv.user.current
+

+
+Get the UUID of an object that was retrieved using the SDK:
+
+
+current_user_uuid = current_user[:uuid]
+

diff --git a/doc/sdk/ruby/index.html.textile.liquid b/doc/sdk/ruby/index.html.textile.liquid
index b78a37d03a..5ad02543ef 100644
--- a/doc/sdk/ruby/index.html.textile.liquid
+++ b/doc/sdk/ruby/index.html.textile.liquid
@@ -2,8 +2,7 @@
 layout: default
 navsection: sdk
 navmenu: Ruby
-title: "Ruby SDK"
-
+title: "Installation"
 ...
 
 The Ruby SDK provides a generic set of wrappers so you can make API calls easily.
@@ -52,74 +51,3 @@ EOF
 arvados.v1.users.current.full_name = 'Your Name'
- -h3. Examples - -Import the module (we skipped this step above by using "ruby -r arvados"): - - -
require 'arvados'
-
- - -Set up an API client user agent: - - -
arv = Arvados.new(apiVersion: 'v1')
-
- - -Get the User object for the current user: - - -
current_user = arv.user.current
-
- - -Get the UUID of an object that was retrieved using the SDK: - - -
current_user_uuid = current_user[:uuid]
-
- - -Retrieve an object by ID: - - -
some_user = arv.user.get(uuid: current_user_uuid)
-
- - -Create an object: - - -
new_link = arv.link.create(link: {link_class: 'test', name: 'test'})
-
- - -Update an object: - - -
updated_link = arv.link.update(uuid: new_link[:uuid],
-                               link: {properties: {foo: 'bar'}})
-
- - -Delete an object: - - -
arv.link.delete(uuid: new_link[:uuid])
-
- - -Get a list of objects: - - -
repos = arv.repository.list
-first_repo = repos[:items][0]
-puts "UUID of first repo returned is #{first_repo[:uuid]}"
-UUID of first repo returned is qr1hi-s0uqq-b1bnybpx3u5temz
-
- - -The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version. -- 2.30.2