From 66c9adddc4dbab2314b70a34f72b09ac5a8e67df Mon Sep 17 00:00:00 2001 From: Parth Shandilya Date: Fri, 7 Jan 2022 13:56:41 +0100 Subject: [PATCH 1/4] docs: Update the analysis docs --- docs/chapters/analysis.md | 218 ++++++++++---------------- docs/chapters/installation_and_use.md | 20 +-- 2 files changed, 93 insertions(+), 145 deletions(-) diff --git a/docs/chapters/analysis.md b/docs/chapters/analysis.md index b325643..50de504 100644 --- a/docs/chapters/analysis.md +++ b/docs/chapters/analysis.md @@ -1,6 +1,6 @@ ## Analysis -The `analysis` command group allows the user to interact with their analyses through the terminal. The supported commands are the following: +The `analysis` command group allows users to interact with their analyses through the terminal. The supported commands are the following: ``` **[terminal] @@ -17,68 +17,25 @@ Commands: delete Delete your analysis. get List your draft analysis. get-published List your published analysis. - publish Publish analysis with given pid. + publish Publish analysis with given PID. schema Get JSON schema for analysis metadata. types List all types of analysis you can create. ``` +### Create an analysis +#### Description -#### List available analysis types +- Allows the user to create a new analysis. +- To create a new analysis, the user needs to pass metadata in a JSON format (either from a file or directly from the terminal). +- The user needs to know the structure of the analysis, use the `analysis schema ` command to check for valid metadata. +- The supported options are the following: -**Description:** - -Using this command the user can take a quick look at which analysis types are available to them, in order to use it for the creation of a new analysis. - -**Usage:** - -``` -**[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis types] -[ - "alice-analysis", - "atlas-analysis". - ... -] -``` - - -#### Retrieve the schema of an analysis type - -**Description:** - -Allows the user retrieve the JSON schema of a specified analysis type. - -**Usage:** - -``` -**[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis schema ] -{ - "$schema": "http://json-schema.org/draft-04/schema#", - "additionalProperties": true, - "dependencies": { - "analysis_reuse_mode": { - "properties": { - ... -} -``` - -**Options:** - -| Name | Type | Desc | -| :-------------- | :----- | :---------------------------------------------------------------------- | -| ANALYSIS_TYPE | TEXT | Type of analysis [required] | -| --version | TEXT | Version of the schema | -| --for-published | FLAG | Show schema for published analysis (may be different than draft schema) | - - -#### Create a new analysis - -**Description:** - -Allows the user to create a new analysis. - -**Usage:** +| Name | Type | Desc | +| :--------------- | :------- | :---------------------------------------------------------------- | +| --json / -j | TEXT | JSON data from command line. (mutually exclusive with --jsonfile) | +| --jsonfile / -f | FILENAME | JSON file. (mutually exclusive with --json) | +| --type / -t | TEXT | Type of analysis | +#### Usage ``` **[terminal] @@ -91,68 +48,39 @@ Allows the user to create a new analysis. } ``` -**Extended Description:** - -In order to create a new analysis, the user needs to pass metadata in a JSON format (either from a file or directly from the terminal). The user needs to know the structure of the analysis, in order to provide valid metadata (use `analysis schema ` command to check). - -**Options:** +### Delete an analysis +#### Description -| Name | Type | Desc | -| :---------- | :------- | :---------------------------------------------------------------- | -| --json | TEXT | JSON data from command line. (mutually exclusive with --jsonfile) | -| --jsonfile | FILENAME | JSON file. (mutually exclusive with --json) | -| --type / -t | TEXT | Type of analysis | - - -#### Delete an analysis - -**Description:** - -Allows the user to delete an analysis draft. - -**Usage:** - -``` -**[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis delete --pid ] -Analysis has been deleted -``` - -**Options:** +- Allows the user to delete an analysis draft. +- Note that the published analysis cannot be deleted. +- The supported options are the following: | Name | Type | Desc | | :---------- | :------- | :---------------------------------------------------- | | --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | - - -#### Publish an analysis - -**Description:** - -Allows the user to publish an analysis (removing it from the drafts), and get the new PID of the published analysis. - -**Usage:** +#### Usage ``` **[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis publish --pid ] -Your analysis has been published with PID: CAP.XXX.ABCD.ABCD +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis delete --pid ] +Analysis has been deleted ``` -**Options:** - -| Name | Type | Desc | -| :---------- | :------- | :---------------------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | - - -#### Get analysis drafts +### Get analysis drafts +#### Description -**Description:** +- Allows retrieving one or more drafts analyses accessible to the user. +- The user can use the `get` command for three cases: + - Retrieve all the draft analyses they have created. + - Retrieve a single draft analysis by its PID. + - Retrieve the draft analyses available to them (both created by them and given access to them by other users). +- The supported options are the following: -Allows the user to retrieve one or more analysis drafts, that they have access to. - -**Usage:** +| Name | Type | Desc | +| :---------- | :------- | :---------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | +| --all | FLAG | Show all (not only yours) | +#### Usage ``` **[terminal] @@ -197,31 +125,23 @@ Allows the user to retrieve one or more analysis drafts, that they have access t ] ``` -**Extended Description:** - -There are 3 separate situations, that the user may need to use the `get` command for: - -1. Retrieve all the draft analysis they have created. -2. Retrieve a single draft analysis by its PID. -3. Retrieve the draft analyses available to them (both created by them and given access to them by other users). +#### Get published analyses -The two additional arguments presented above, are used for cases 2 and 3. +#### Description -**Options:** +- Allows retrieving one or more published analyses accessible to the user. +- The user can use the `get-published` command for three cases + - Retrieve all the published analyses they have created. + - Retrieve a single published analysis by its PID. + - Retrieve the published analyses available to them (both created by them and given access to them by other users). +- The supported options are the following: | Name | Type | Desc | | :---------- | :------- | :---------------------------------------- | | --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | | --all | FLAG | Show all (not only yours) | - -#### Get published analyses - -**Description:** - -Allows the user to retrieve one or more published analyses, that they have access to. - -**Usage:** +#### Usage ``` **[terminal] @@ -270,20 +190,48 @@ Allows the user to retrieve one or more published analyses, that they have acces ] ``` -**Extended Description:** +### Retrieve the schema of an analysis type + +#### Description + +- Allows the user to retrieve the JSON schema of a specified analysis type. +- The supported options are the following: + +| Name | Type | Desc | +| :-------------- | :----- | :---------------------------------------------------------------------- | +| ANALYSIS_TYPE | TEXT | Type of analysis [required] | +| --version | TEXT | Version of the schema | +| --for-published | FLAG | Show schema for published analysis (may be different from draft schema) | + +#### Usage +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis schema ] +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "additionalProperties": true, + "dependencies": { + "analysis_reuse_mode": { + "properties": { + ... +} +``` -There are 3 separate situations, that the user may need to use the `get-published` command for: +### List available analysis types -1. Retrieve all the published analysis they have created. -2. Retrieve a single published analysis by its PID. -3. Retrieve the published analyses available to them (both created by them and given access to them by other users). +#### Description -The two additional arguments presented above, are used for cases 2 and 3. +- The user can take a quick look at which analysis types are available to create a new analysis. -**Options:** +#### Usage -| Name | Type | Desc | -| :---------- | :------- | :---------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | -| --all | FLAG | Show all (not only yours) | \ No newline at end of file +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis types] +[ + "alice-analysis", + "atlas-analysis". + ... +] +``` diff --git a/docs/chapters/installation_and_use.md b/docs/chapters/installation_and_use.md index 3e3c9c9..1b06d58 100644 --- a/docs/chapters/installation_and_use.md +++ b/docs/chapters/installation_and_use.md @@ -1,6 +1,6 @@ ## Installation -CAP-client supports Python versions `2.7` and `3.5+`, and is available on PyPI. You can install it using the following command: +The cap-client supports Python versions `2.7` and `3` and is available on PyPI. You can install it using the following command: ``` **[terminal] @@ -9,23 +9,23 @@ CAP-client supports Python versions `2.7` and `3.5+`, and is available on PyPI. ## Usage -The cap-client is designed to communicate with a *CERN Analysis Preservation (CAP)* server instance. You can use the [CERN Analysis Preservation Production Server](https://analysispreservation.cern.ch/), which comes with the latest production version of CAP. All further descriptions and references link to this production instance. +The cap-client is designed to communicate with a CERN Analysis Preservation (CAP) server instance. You can use the [CERN Analysis Preservation Production Server](https://analysispreservation.cern.ch/), which comes with the latest production version of CAP. All further descriptions and references link to this production instance. -In order to communicate with the server, you first need to generate your personal access token [here](https://analysispreservation-dev.cern.ch/settings), after logging in with your CERN credentials, and export it to your local environment. +In order to communicate with the server, you need to first generate personal access token [here](https://analysispreservation-dev.cern.ch/settings) after logging in with your CERN credentials and exporting it to your local environment. ``` **[terminal] **[prompt user@pc]**[path ~]**[delimiter $ ]**[command export CAP_ACCESS_TOKEN=] ``` -Alternatively, in case you want to explore and experiment with CAP-Client, you can export and use our development server instance (which you can access [here](https://analysispreservation-dev.cern.ch/settings) in order to get the assorted dev server token). +Alternatively, in case you want to explore and experiment with cap-client, you can export and use our development server instance (which you can access [here](https://analysispreservation-dev.cern.ch/settings) to get the development server token). ``` **[terminal] **[prompt user@pc]**[path ~]**[delimiter $ ]**[command export CAP_SERVER_URL=https://analysispreservation-dev.cern.ch/] ``` -After setting up the environment variables, you are ready to start using CERN Analysis Preservation for a variety of tasks, that will be described in the following chapters. In case you need a quick rundown of the command groups (or specific instructions for each command), you can use the `--help` argument: +After setting up the environment variables, you are ready to start using CAP for various tasks, which will be described in the following chapters. In case you need a quick rundown of the command groups (or specific instructions for each command), you can use the `--help` argument: ``` **[terminal] @@ -35,10 +35,10 @@ Usage: cap-client [OPTIONS] COMMAND [ARGS]... CAP command line interface. Options: - -v, --verbose Verbose output - -l, --loglevel [error|debug|info] - Sets log level - --help Show this message and exit. + -v, --verbose Verbose output + -l, --loglevel [error|debug|info] Sets log level + --version Show the version and exit. + --help Show this message and exit. Commands: analysis Manage your analysis. @@ -46,4 +46,4 @@ Commands: metadata Manage analysis metadata. permissions Manage analysis permissions. repositories Manage analysis repositories and webhooks. -``` \ No newline at end of file +``` From 9453781abd2e012bda0fdb56e132dc77739cffa9 Mon Sep 17 00:00:00 2001 From: Parth Shandilya Date: Fri, 7 Jan 2022 15:00:09 +0100 Subject: [PATCH 2/4] docs: Update the metadata command docs --- docs/chapters/metadata.md | 104 +++++++++++++++++++++++--------------- 1 file changed, 64 insertions(+), 40 deletions(-) diff --git a/docs/chapters/metadata.md b/docs/chapters/metadata.md index 8cc7c53..1029906 100644 --- a/docs/chapters/metadata.md +++ b/docs/chapters/metadata.md @@ -19,13 +19,21 @@ Commands: ``` -#### Retrieve analysis metadata +### Retrieve analysis metadata -**Description:** +#### Description -Allows the user to retrieve the metadata of a specified analysis. The user can retrieve the whole JSON object, or select a specific field to be returned. In addition, the command supports the dot operator (e.g. `basic_info.abstract`), in order to define nested fields or list indices, allowing the user to retrieve every piece of metadata autonomously, if needed. +- Allows the user to retrieve the metadata of a specified analysis. +- The user can retrieve the whole JSON object, or select a specific field to be returned. +- The command supports the dot operator (e.g. `basic_info.abstract`) to define nested fields or list indices, allowing the user to retrieve every piece of metadata autonomously. +- The supported options are the following: -**Usage:** +| Name | Type | Desc | +| :---------- | :----- | :---------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +| --field | TEXT | Specify field, eg. object.nested_array.0 | + +#### Usage ``` **[terminal] @@ -54,21 +62,23 @@ Allows the user to retrieve the metadata of a specified analysis. The user can r "AN-1234/123" ``` -**Options:** - -| Name | Type | Desc | -| :---------- | :----- | :---------------------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -| --field | TEXT | Specify field, eg. object.nested_array.0 | - - -#### Update an analysis +### Update an analysis -**Description:** +#### Description -Allows the user to update the metadata of an analysis, or a specific field only, using a valid JSON. +- Allows the user to update the metadata of an analysis. +- The JSON object can be passed as it is through the cli or bypassing the file name of the JSON file that contains it. +- The supported options are the following: -**Usage:** +| Name | Type | Desc | +| :-------------- | :------- | :---------------------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +| --field | TEXT | Specify an existing field, eg. object.nested_array.0 | +| --json / -j | TEXT | JSON data (mutually exclusive with --jsonfile, --text, --num) | +| --jsonfile / -f | FILENAME | JSON file (mutually exclusive with --json, --text, --num) | +| --text / -t | TEXT | Text data (mutually exclusive with --jsonfile, --json, --num) | +| --num / -n | FILENAME | Numeric data (mutually exclusive with --json, --jsonfile, --text) | +#### Usage ``` **[terminal] @@ -88,7 +98,7 @@ Allows the user to update the metadata of an analysis, or a specific field only, ``` **[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client metadata get --pid --field basic_info.abstract --json \"new abstract\"] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client metadata update --pid --field basic_info.abstract --json \"new abstract\"] { "created": "2020-04-23T14:24:44.068071+00:00", "metadata": { @@ -104,7 +114,7 @@ Allows the user to update the metadata of an analysis, or a specific field only, ``` **[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client metadata get --pid --jsonfile JSONFILE] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client metadata update --pid --jsonfile JSONFILE] { "created": "2020-04-23T14:24:44.068071+00:00", "metadata": { @@ -118,27 +128,48 @@ Allows the user to update the metadata of an analysis, or a specific field only, } ``` -**Extended Description:** - -The JSON object can be passed as-is through the cli, or by passing the file name of the JSON file that contains it. It is important to keep in mind that single numbers, or even text in quotes (that need escaping, e.g. `\"`), is considered valid JSON, which allows the user to also update text/numeric fields easily. - -**Options:** +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client metadata update --pid --field general_title --text new-test] +{ + "created": "2020-04-23T14:24:44.068071+00:00", + "metadata": { + "basic_info": { + "abstract": "new abstract" + }, + "general_title": "new-test" + }, + "pid": "796be0cc6d314e25b9c11dc0864e8d32", + "updated": "2020-04-23T14:36:45.175490+00:00" +} +``` -| Name | Type | Desc | -| :--------- | :------- | :------------------------------------------------------ | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -| --field | TEXT | Specify an existing field, eg. object.nested_array.0 | -| --json | TEXT | JSON data or text. (mutually exclusive with --jsonfile) | -| --jsonfile | FILENAME | JSON file. (mutually exclusive with --json) | +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client metadata update --pid myfield --num 1.2] +{ + "created": "2020-04-23T14:24:44.068071+00:00", + "metadata": { + "myfield": 1.2 + }, + "pid": "796be0cc6d314e25b9c11dc0864e8d32", + "updated": "2020-04-23T14:36:45.175490+00:00" +} +``` +### Remove a metadata field -#### Remove a metadata field +#### Description -**Description:** +- Allows the user to remove a specified metadata field from an analysis. +- The supported options are the following: -Allows the user to remove a specified metadata field from an analysis. +| Name | Type | Desc | +| :--------- | :------- | :-------------------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +| --field | TEXT | Specify an existing field, eg. object.nested_array.0 [required] | -**Usage:** +#### Usage ``` **[terminal] @@ -148,10 +179,3 @@ Allows the user to remove a specified metadata field from an analysis. "general_title": "test" } ``` - -**Options:** - -| Name | Type | Desc | -| :--------- | :------- | :-------------------------------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -| --field | TEXT | Specify an existing field, eg. object.nested_array.0 [required] | From a7ae6d3663695f8fc09323bc312a10f4a0bd155b Mon Sep 17 00:00:00 2001 From: Parth Shandilya Date: Fri, 7 Jan 2022 15:12:39 +0100 Subject: [PATCH 3/4] docs: Update the permission command docs --- docs/chapters/permissions.md | 108 +++++++++++++++++------------------ 1 file changed, 52 insertions(+), 56 deletions(-) diff --git a/docs/chapters/permissions.md b/docs/chapters/permissions.md index 2b721cd..5761409 100644 --- a/docs/chapters/permissions.md +++ b/docs/chapters/permissions.md @@ -18,18 +18,26 @@ Commands: remove Remove user/egroup permissions for your analysis. ``` +### Add user/e-group permissions to an analysis -#### Retrieve the permissions of an analysis +#### Description -**Description:** +- Allows the user to add permissions of a specified analysis. +- The user can add permissions to a specific user or a whole e-group. +- The supported options are the following: -Allows the user to retrieve the permissions of a specified analysis. +| Name | Type | Desc | +| :------------ | :----- | :---------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +| --user / -u | TEXT | User mail. (mutually exclusive with --egroup) | +| --egroup / -e | TEXT | Egroup mail. (mutually exclusive with --user) | +| --rights / -r | TEXT | Options: read / update / admin [required] | -**Usage:** +#### Usage ``` **[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions get --pid ] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions add --pid --user info@inveniosoftware.org --rights read|update] { 'deposit-admin': { 'roles': [], @@ -37,33 +45,50 @@ Allows the user to retrieve the permissions of a specified analysis. }, 'deposit-read': { 'roles': [], - 'users': ['user@inveniosoftware.org'] + 'users': ['user@inveniosoftware.org', info@inveniosoftware.org] }, 'deposit-update': { 'roles': [], - 'users': ['user@inveniosoftware.org'] + 'users': ['user@inveniosoftware.org', info@inveniosoftware.org] } } ``` -**Options:** - -| Name | Type | Desc | -| :---------- | :----- | :---------------------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions add --pid --egroup egroup@inveniosoftware.org --rights read] +{ + "deposit-admin": { + "roles": [], + "users": ["info@inveniosoftware.org"] + }, + "deposit-read": { + "roles": ['egroup@inveniosoftware.org'], + "users": ["info@inveniosoftware.org"] + }, + "deposit-update": { + "roles": [], + "users": ["info@inveniosoftware.org"] + } + } +``` +### Retrieve the permissions of an analysis -#### Add user/e-group permissions to an analysis +#### Description -**Description:** +- Allows the user to retrieve the permissions of a specified analysis. +- The supported options are the following: -Allows the user to add permissions of a specified analysis. The user can add permissions to a specific user or a whole e-group. +| Name | Type | Desc | +| :---------- | :----- | :---------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -**Usage:** +#### Usage ``` **[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions add --pid --user info@inveniosoftware.org --rights read|update] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions get --pid ] { 'deposit-admin': { 'roles': [], @@ -71,35 +96,22 @@ Allows the user to add permissions of a specified analysis. The user can add per }, 'deposit-read': { 'roles': [], - 'users': ['user@inveniosoftware.org', info@inveniosoftware.org] + 'users': ['user@inveniosoftware.org'] }, 'deposit-update': { 'roles': [], - 'users': ['user@inveniosoftware.org', info@inveniosoftware.org] + 'users': ['user@inveniosoftware.org'] } } ``` -``` -**[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions add --pid --egroup egroup@inveniosoftware.org --rights read] -{ - "deposit-admin": { - "roles": [], - "users": ["info@inveniosoftware.org"] - }, - "deposit-read": { - "roles": ['egroup@inveniosoftware.org'], - "users": ["info@inveniosoftware.org"] - }, - "deposit-update": { - "roles": [], - "users": ["info@inveniosoftware.org"] - } - } -``` +### Remove user/e-group permissions from an analysis + +#### Description -**Options:** +- Allows the user to remove permissions from a specified analysis. +- The user can remove permissions from a specific user or a whole e-group. +- The supported options are the following: | Name | Type | Desc | | :------------ | :----- | :---------------------------------------------------- | @@ -108,14 +120,7 @@ Allows the user to add permissions of a specified analysis. The user can add per | --egroup / -e | TEXT | Egroup mail. (mutually exclusive with --user) | | --rights / -r | TEXT | Options: read / update / admin [required] | - -#### Remove user/e-group permissions from an analysis - -**Description:** - -Allows the user to remove permissions from a specified analysis. The user can remove permissions from a specific user or a whole e-group. - -**Usage:** +#### Usage ``` **[terminal] @@ -138,7 +143,7 @@ Allows the user to remove permissions from a specified analysis. The user can re ``` **[terminal] -**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions add --pid --egroup egroup@inveniosoftware.org --rights read] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client permissions remove --pid --egroup egroup@inveniosoftware.org --rights read] { "deposit-admin": { "roles": [], @@ -154,12 +159,3 @@ Allows the user to remove permissions from a specified analysis. The user can re } } ``` - -**Options:** - -| Name | Type | Desc | -| :------------ | :----- | :---------------------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -| --user / -u | TEXT | User mail. (mutually exclusive with --egroup) | -| --egroup / -e | TEXT | Egroup mail. (mutually exclusive with --user) | -| --rights / -r | TEXT | Options: read / update / admin [required] | From 30fdab41aa35480a64584b29b734734ffbd73768 Mon Sep 17 00:00:00 2001 From: Parth Shandilya Date: Fri, 7 Jan 2022 15:32:57 +0100 Subject: [PATCH 4/4] docs: Update the repositories command docs --- docs/SUMMARY.md | 9 ++--- docs/chapters/analysis.md | 68 +++++++++++++++++++++++++++++----- docs/chapters/repositories.md | 69 ++++++++++++++++------------------- 3 files changed, 94 insertions(+), 52 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 765fa9e..373de87 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,13 +3,12 @@ * [1. Introduction](README.md) * [2. Installation & Usage](chapters/installation_and_use.md) * [3. Analysis](chapters/analysis.md) - * [List available analysis types](chapters/analysis.md#list-available-analysis-types) - * [Retrieve the schema of an analysis type](chapters/analysis.md#retrieve-the-schema-of-an-analysis-type) - * [Create a new analysis](chapters/analysis.md#create-a-new-analysis) + * [Create an analysis](chapters/analysis.md#create-an-analysis) * [Delete an analysis](chapters/analysis.md#delete-an-analysis) - * [Publish an analysis](chapters/analysis.md#publish-an-analysis) - * [Get analysis drafts](chapters/analysis.md#get-analysis-drafts) + * [Get drafts analyses](chapters/analysis.md#get-analysis-drafts) * [Get published analyses](chapters/analysis.md#get-published-analyses) + * [Retrieve the schema of an analysis type](chapters/analysis.md#retrieve-the-schema-of-an-analysis-type) + * [List available analysis types](chapters/analysis.md#list-available-analysis-types) * [5. Metadata](chapters/metadata.md) * [Retrieve analysis metadata](chapters/metadata.md#retrieve-analysis-metadata) * [Update an analysis](chapters/metadata.md#update-an-analysis) diff --git a/docs/chapters/analysis.md b/docs/chapters/analysis.md index 50de504..5bdbcc0 100644 --- a/docs/chapters/analysis.md +++ b/docs/chapters/analysis.md @@ -66,7 +66,7 @@ Commands: Analysis has been deleted ``` -### Get analysis drafts +### Get drafts analyses #### Description - Allows retrieving one or more drafts analyses accessible to the user. @@ -76,10 +76,16 @@ Analysis has been deleted - Retrieve the draft analyses available to them (both created by them and given access to them by other users). - The supported options are the following: -| Name | Type | Desc | -| :---------- | :------- | :---------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | -| --all | FLAG | Show all (not only yours) | +| Name | Type | Desc | +| :----------- | :------- | :--------------------------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | +| --all | FLAG | Show all (not only yours) | +| --query / -q | TEXT | A free text query (e.g `test` or `basic_info.analysis_title:test`) | +| ----search / -s | TEXT | Search through facets (e.g. `type=my-analysis`) | +| --type / -t | TEXT | Type of analysis | +| --sort | TEXT | The available values are "bestmatch", "mostrecent" [default=mostrecent]| +| --page | INT | Shows results on the specified page. [default=1] | +| --size | INT | Number of results on a page. [default=10] | #### Usage ``` @@ -125,7 +131,43 @@ Analysis has been deleted ] ``` -#### Get published analyses +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis get -q basic_info.analysis_title:test] +[ + { + "created": "2022-01-05T08:57:08.661809+00:00", + "metadata": { + "basic_info": { + "analysis_title": "Test" + }, + "general_title": "Test Alice" + }, + "pid": "3ec3b81e4f3643ce91e4396891dbcb03", + "updated": "2022-01-05T08:57:22.734703+00:00" + } +] +``` + +``` +**[terminal] +**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis get -s type=alice-analysis] +[ + { + "created": "2022-01-05T08:57:08.661809+00:00", + "metadata": { + "basic_info": { + "analysis_title": "Test" + }, + "general_title": "Test Alice" + }, + "pid": "3ec3b81e4f3643ce91e4396891dbcb03", + "updated": "2022-01-05T08:57:22.734703+00:00" + } +] +``` + +### Get published analyses #### Description @@ -136,10 +178,16 @@ Analysis has been deleted - Retrieve the published analyses available to them (both created by them and given access to them by other users). - The supported options are the following: -| Name | Type | Desc | -| :---------- | :------- | :---------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | -| --all | FLAG | Show all (not only yours) | +| Name | Type | Desc | +| :----------- | :------- | :--------------------------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) | +| --all | FLAG | Show all (not only yours) | +| --query / -q | TEXT | A free text query (e.g `test` or `basic_info.analysis_title:test`) | +| ----search / -s | TEXT | Search through facets (e.g. `type=my-analysis`) | +| --type / -t | TEXT | Type of analysis | +| --sort | TEXT | The available values are "bestmatch", "mostrecent" [default=mostrecent]| +| --page | INT | Shows results on the specified page. [default=1] | +| --size | INT | Number of results on a page. [default=10] | #### Usage diff --git a/docs/chapters/repositories.md b/docs/chapters/repositories.md index c2e8ff4..57f37b2 100644 --- a/docs/chapters/repositories.md +++ b/docs/chapters/repositories.md @@ -1,14 +1,13 @@ ## Repositories -The `repositories` command group allows the user to manage the repositories attached to an analysis. More specifically, the user can: - +The `repositories` command group allows the user to manage the repositories attached to an analysis. The user can: - retrieve the repositories attached to an analysis, -- upload a repository to an analysis using its GitHub/GitLab url, and +- upload a repository to an analysis using its GitHub/GitLab URL, and - connect a repo to the analysis through webhooks. -By leveraging the webhook API that GitHub and GitLab support, the users can easily define certain git actions (release, push), that will trigger an update to their analysis' repos. That way, every time e.g. a new release happens on a repo, the analysis repo will be updated, enabling the user to have the most up-to-date code saved to the CAP server. +The users can define release and push actions that will trigger an update to their analysis repository by leveraging the webhook API of GitHub/GitLab. That way, every time, e.g., a new release happens on a repo, the analysis repo will be updated, enabling the user to have the most up-to-date code saved to the CAP analysis. -Every time the repo is updated, a new `snapshot` of the repo will be created, which means, that although the most recent version is readily available, older versions are also preserved. +Every time the repo is updated, a new `snapshot` of the repo will be created, which means that although the most recent version is readily available, older versions are also preserved. ``` **[terminal] @@ -26,14 +25,20 @@ Commands: upload Upload repository tarball to your analysis. ``` +### Get the repositories connected to an analysis -#### Get the repositories connected to an analysis +#### Description -**Description:** +- Allows the user to retrieve connected repositories of analysis, including the different snapshots of every repo. +- Snapshot is the local copy of the repository created after an event triggered the specified webhook. +- The supported options are the following: -Allows the user to retrieve connected repositories of an analysis, including the different snapshots of every repo. Snapshot is the local copy of the repo, that was created after an event triggered the specified webhook. +| Name | Type | Desc | +| :--------------------- | :----- | :---------------------------------------------------- | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +| --with-snapshots / -ws | FLAG | Show snapshots. | -**Usage:** +#### Usage ``` **[terminal] @@ -62,21 +67,19 @@ Allows the user to retrieve connected repositories of an analysis, including the }] ``` -**Options:** - -| Name | Type | Desc | -| :--------------------- | :----- | :---------------------------------------------------- | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -| --with-snapshots / -ws | FLAG | Show snapshots. | +### Upload a repository to an analysis +#### Description -#### Upload a repository to an analysis +- Allows the user to upload a repository and attach it to their analysis by providing the correct GitHub/GitLab URL. +- The supported options are the following: -**Description:** - -Allows the user to upload a repository and attach it to their analysis, by providing the correct GitHub/GitLab url. +| Name | Type | Desc | +| :--------- | :----- | :---------------------------------------------------- | +| URL | TEXT | The GitHub/GitLab url [required] | +| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -**Usage:** +#### Usage ``` **[terminal] @@ -84,21 +87,21 @@ Allows the user to upload a repository and attach it to their analysis, by provi Repository tarball was saved with your analysis files. (access using `cap-client files` methods) ``` -**Options:** +### Connect a repository to an analysis + +#### Description + +- Allows the user to connect a repository to a specified analysis. +- The user can specify in which event the repo will get updated on the CAP analysis. +- The supported options are the following: | Name | Type | Desc | | :--------- | :----- | :---------------------------------------------------- | | URL | TEXT | The GitHub/GitLab url [required] | | --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | +| --event | TEXT | Download repository tarball on every (push / release) | - -#### Connect a repository to an analysis - -**Description:** - -Allows the user to connect a repository to a specified analysis. The user can specify in which event the repo will get updated on the CAP server. - -**Usage:** +#### Usage ``` **[terminal] @@ -106,11 +109,3 @@ Allows the user to connect a repository to a specified analysis. The user can sp Repository was connected with analysis. Now on every release, we will attach the latest version to your analysis. ``` - -**Options:** - -| Name | Type | Desc | -| :--------- | :----- | :---------------------------------------------------- | -| URL | TEXT | The GitHub/GitLab url [required] | -| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] | -| --event | TEXT | Download repository tarball on every (push / release) |