From c0689d885615c0aeba4cb73df78105abde40e5ce Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 10:05:06 +0200 Subject: [PATCH 1/9] #187 delete data contribution guide from feelpp/toolbox --- contribute/modules/girder/nav.adoc | 13 -- contribute/modules/girder/pages/README.adoc | 51 ------- contribute/modules/girder/pages/api_keys.adoc | 79 ---------- .../modules/girder/pages/python_scripts.adoc | 137 ------------------ 4 files changed, 280 deletions(-) delete mode 100644 contribute/modules/girder/nav.adoc delete mode 100644 contribute/modules/girder/pages/README.adoc delete mode 100644 contribute/modules/girder/pages/api_keys.adoc delete mode 100644 contribute/modules/girder/pages/python_scripts.adoc diff --git a/contribute/modules/girder/nav.adoc b/contribute/modules/girder/nav.adoc deleted file mode 100644 index 9b4e4840..00000000 --- a/contribute/modules/girder/nav.adoc +++ /dev/null @@ -1,13 +0,0 @@ -* xref:README.adoc[How to contribute data with Girder] -** xref:README.adoc#_what_is_girder[What is Girder] -** xref:README.adoc#_file_access_options[File access options] -*** xref:README.adoc#_web_browser_ui[Web brower UI] -*** xref:README.adoc#_python_api[Python API] -** xref:python_scripts.adoc[Python scripts examples] -*** xref:python_scripts.adoc#_with_user_and_password[With user and password] -**** xref:python_scripts.adoc#_what_not_to_do[What not to do] -**** xref:python_scripts.adoc#_interactive_download[Interactive download] -**** xref:python_scripts.adoc#_interactive_upload[Interactive upload] -*** xref:api_keys.adoc#_using_api_keys[Using API keys] -**** xref:api_keys.adoc#_download[Download] -**** xref:api_keys.adoc#_upload[Upload] diff --git a/contribute/modules/girder/pages/README.adoc b/contribute/modules/girder/pages/README.adoc deleted file mode 100644 index 8357c6f2..00000000 --- a/contribute/modules/girder/pages/README.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= Girder - -== What is Girder - -Girder is a data management platform. -It can be used to store (large) files such as meshes, simulation results, etc... -Read more about it in the {feelpp} xref:data:ROOT:data-storage.adoc[data manual] or -link:http://girder.readthedocs.io/[on the official website]. - -== File access options - -A big advantage of girder is that files can be accessed either with a nice user -interface (in a web browser) or more programmatically (via CLI or programming -interfaces). -This is true for both upload and download. - -=== Web browser UI - -If you are new to Girder, you should start with the web user interface to -discover the service. -You are encouraged to read the documentation -link:http://girder.readthedocs.io/[documentation] and especially the -link:http://girder.readthedocs.io/en/latest/user-docs.html[user guide]. -For example, using a web browser, you can reach -link:https://girder.math.unistra.fr/#collections[our server]. - -|=== -| image:girder_web_ui.png[Web user interface,100%] -|=== - -NOTE: This is quite straightforward and it should illustrate important concepts -and help better visualize the following section. - -=== Python API - -To download or upload a file using python, we have two options. -We can either use a login system (user + password) or an API key. -- With the user/password, we will need to provide a user and a password to -access files, just like a human would do using the UI. -- With an API key, the script only needs an API key. -This means we do not need to have an account on the Girder server. - -In both cases, similar pieces of information are required: - -- an *address* (URL): to reach the server, -- a *file ID*: to tell which file/directory we want to manipulate, -- either a *user/password* pair or an *API key*: to grant access to the -required file(s). - -Let's check out some -xref:contribute:girder:python_scripts.adoc[scripts]. diff --git a/contribute/modules/girder/pages/api_keys.adoc b/contribute/modules/girder/pages/api_keys.adoc deleted file mode 100644 index a77522a4..00000000 --- a/contribute/modules/girder/pages/api_keys.adoc +++ /dev/null @@ -1,79 +0,0 @@ -= Using API keys - -An API key grants access to a certain set of files, with various permissions. -It is very useful and quite convenient to use. -Since it is nothing more than a character string, one could think of it as a -long and pseudorandom special password. - -NOTE: To learn how to set API keys, read -link:http://girder.readthedocs.io/en/latest/user-guide.html#api-keys[this part] -of the documentation. - -== Download - -To use an API key to download a file, see this script: - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using only the API key -gc.authenticate(apiKey='KEY') # <1> - -# We download the file using its file ID. The path indicates where the file -# should be written (the full file name should be included at the end of the path) -gc.downloadFile(fileId='FILEID', path='PATH') # <2> - ----- - -<1> *KEY* is the only needed information to authenticate. - -<2> *FILEID* should be replaced by the actual Girder file ID and *PATH* should -be the path where to store the results, including the desired file name and -extension. - - -== Upload - -To upload using an API key: - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using only the API key -gc.authenticate(apiKey='KEY') # <1> - -# /!\ This is mandatory: we have to open the file in read mode before -# uploading it -f = open('PATH', 'r') # <2> - -# Now we can upload the file <3> -gc.uploadFile(parentId='PID', stream=f, name="NAME", size=SIZE, parentType='TYPE') - ----- - -<1> *KEY* is the only needed information to authenticate. - -<2> *PATH* should be replaced by the full path to the file to read. -*r* stands for "read mode". - -<3> *PID* should be replaced by the parent directory ID (on the Girder server). -*f* is the read stream defined previously . -*NAME* should be replaced by the desired file name (on the Girder server). -*SIZE* should be replaced by the file size (in bytes). -*TYPE* is either *folder*, *user*, or *collection*. diff --git a/contribute/modules/girder/pages/python_scripts.adoc b/contribute/modules/girder/pages/python_scripts.adoc deleted file mode 100644 index 34d94f40..00000000 --- a/contribute/modules/girder/pages/python_scripts.adoc +++ /dev/null @@ -1,137 +0,0 @@ -= Python scripts - -Here, we provide some python scripts to access files on Girder. -To be able to use them, please install the girder client python module (read how -link:http://girder.readthedocs.io/en/latest/python-client.html[here]. -) - -== With user and password - -=== What not to do - -WARNING: The following script is only meant as a first approach to understand -how the module works. -You should not use it because it requires your password to be written in clear -in the script. -Use the xref:python_scripts.adoc#_interactive_download[interactive version] -instead. - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using the username and the password. -# /!\ This is for learning purpose. -# For security reasons, you should never put your password in the script. -gc.authenticate(username='USER', password='PASSWORD') # <1> - -# We download the file using its file ID. The path indicates where the file -# should be written (the file name should be included at the end of the path) -gc.downloadFile(fileId='FILEID', path='PATH') # <2> - ----- -<1> *USER* should be replaced by the Girder user name, -*PASSWORD* by the corresponding password -<2> *FILEID* should be replaced by the actual Girder file ID and *PATH* should -be the path where to store the results, including the desired file name and -extension. - -WARNING: If you don't supply the file name, the system will not warn you, it -will *automatically generate one*, which could be confusing ! - -IMPORTANT: Remember not to use this script. Try the -xref:python_scripts.adoc#_interactive_download[interactive one] instead. - - -=== Interactive download - -Here, we use a modified version of the _authenticate_ function to use -interactive login. -This means the password will be prompted for at run time. - -IMPORTANT: This implies the script can not be used in a fully automated way, -because each execution of the script will require the user of the script to be -present to type the password. For a safe and automatic access, use the -xref:api_keys.adoc#_using_api_keys[API keys]. - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using the username, the password will be typed at runtime -gc.authenticate(username='USER', interactive=True) # <1> - -# We download the file using its file ID. The path indicates where the file -# should be written (the full file name should be included at the end of the path) -gc.downloadFile(fileId='FILEID', path='PATH') # <2> - ----- -<1> *USER* should be replaced by the Girder user name, and because of the -_interactive=True_ argument, the password will be prompted for at runtime. -<2> *FILEID* should be replaced by the actual Girder file ID and *PATH* should be the path where to store the results, including the desired file name and extension. - -TIP: We can even prompt the user to type *both the user name and the password* -by providing *only* the _interactive=True_ argument ! -This is a better solution when multiple users are likely to use the script only -once or a handful of times each. - -WARNING: If you don't supply the file name, the system will not warn you, it -will *automatically generate one*, which could be confusing ! - - - -=== Interactive upload - -To upload a file, only a few changes are required. - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using the username, the password will be typed at runtime -gc.authenticate(username='USER', interactive=True) # <1> - - -# /!\ This is mandatory: we have to open the file in read mode before -# uploading it -f = open('PATH', 'r') # <2> - -# Now we can upload the file <3> -gc.uploadFile(parentId='PID', stream=f, name="NAME", size=SIZE, parentType='TYPE') - ----- - -<1> *USER* should be replaced by the Girder user name, and because of the -_interactive=True_ argument, the password will be prompted for at runtime. - -<2> *PATH* should be replaced by the full path to the file to read. -*r* stands for "read mode". - -<3> *PID* should be replaced by the parent directory ID (on the Girder server). -*f* is the read stream defined previously . -*NAME* should be replaced by the desired file name (on the Girder server). -*SIZE* should be replaced by the file size (in bytes). -*TYPE* is either *folder*, *user*, or *collection*. - -NOTE: We should try and find a way to get the file size automatically. From 103a0c85174e32e2247abb7d339bd8766425f74d Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 10:51:55 +0200 Subject: [PATCH 2/9] #187 restore girder readme page with partial --- contribute/modules/ROOT/nav.adoc | 2 ++ contribute/modules/girder/images/README.adoc | 1 + 2 files changed, 3 insertions(+) create mode 100644 contribute/modules/girder/images/README.adoc diff --git a/contribute/modules/ROOT/nav.adoc b/contribute/modules/ROOT/nav.adoc index 824ec254..261db55a 100644 --- a/contribute/modules/ROOT/nav.adoc +++ b/contribute/modules/ROOT/nav.adoc @@ -5,3 +5,5 @@ ** xref:index.adoc#contrib-desc[an example or a benchmark description?] ** xref:index.adoc#contrib[an example or a benchmark?] ** xref:vtkjs.adoc[{vtkjs} files?] + +* xref:data:ROOT:partial$girder/README.adoc[How to contribute data with Girder] \ No newline at end of file diff --git a/contribute/modules/girder/images/README.adoc b/contribute/modules/girder/images/README.adoc new file mode 100644 index 00000000..f39cf0fd --- /dev/null +++ b/contribute/modules/girder/images/README.adoc @@ -0,0 +1 @@ +include::data:ROOT:partial$girder/README.adoc \ No newline at end of file From b39dbfe2af2df1e0fb3915d69b1cb013eb9e1b76 Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 10:59:57 +0200 Subject: [PATCH 3/9] #187 fix nav.adoc --- contribute/modules/ROOT/nav.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/modules/ROOT/nav.adoc b/contribute/modules/ROOT/nav.adoc index 261db55a..a6ee676e 100644 --- a/contribute/modules/ROOT/nav.adoc +++ b/contribute/modules/ROOT/nav.adoc @@ -6,4 +6,4 @@ ** xref:index.adoc#contrib[an example or a benchmark?] ** xref:vtkjs.adoc[{vtkjs} files?] -* xref:data:ROOT:partial$girder/README.adoc[How to contribute data with Girder] \ No newline at end of file +* xref:girder/README.adoc[How to contribute data with Girder] \ No newline at end of file From b4ef0cd99692ef99f4bd9a4d06f23830a68e0397 Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 11:09:55 +0200 Subject: [PATCH 4/9] #187 up navs --- contribute/modules/ROOT/nav.adoc | 4 +--- contribute/modules/girder/nav.adoc | 13 +++++++++++++ 2 files changed, 14 insertions(+), 3 deletions(-) create mode 100644 contribute/modules/girder/nav.adoc diff --git a/contribute/modules/ROOT/nav.adoc b/contribute/modules/ROOT/nav.adoc index a6ee676e..d129db78 100644 --- a/contribute/modules/ROOT/nav.adoc +++ b/contribute/modules/ROOT/nav.adoc @@ -4,6 +4,4 @@ .How to contribute ** xref:index.adoc#contrib-desc[an example or a benchmark description?] ** xref:index.adoc#contrib[an example or a benchmark?] -** xref:vtkjs.adoc[{vtkjs} files?] - -* xref:girder/README.adoc[How to contribute data with Girder] \ No newline at end of file +** xref:vtkjs.adoc[{vtkjs} files?] \ No newline at end of file diff --git a/contribute/modules/girder/nav.adoc b/contribute/modules/girder/nav.adoc new file mode 100644 index 00000000..f13f54a2 --- /dev/null +++ b/contribute/modules/girder/nav.adoc @@ -0,0 +1,13 @@ +* xref:README.adoc[How to contribute data with Girder] + ** xref:README.adoc#_what_is_girder[What is Girder] + ** xref:README.adoc#_file_access_options[File access options] + *** xref:README.adoc#_web_browser_ui[Web brower UI] + *** xref:README.adoc#_python_api[Python API] + ** xref:python_scripts.adoc[Python scripts examples] + *** xref:python_scripts.adoc#_with_user_and_password[With user and password] + **** xref:python_scripts.adoc#_what_not_to_do[What not to do] + **** xref:python_scripts.adoc#_interactive_download[Interactive download] + **** xref:python_scripts.adoc#_interactive_upload[Interactive upload] + *** xref:api_keys.adoc#_using_api_keys[Using API keys] + **** xref:api_keys.adoc#_download[Download] + **** xref:api_keys.adoc#_upload[Upload] \ No newline at end of file From f415d5fc8ea52af0ce1b66a9695a18b9c2e61e30 Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 11:18:09 +0200 Subject: [PATCH 5/9] #187 mv Readme and add square bracket in partial --- contribute/modules/girder/README.adoc | 1 + contribute/modules/girder/images/README.adoc | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 contribute/modules/girder/README.adoc delete mode 100644 contribute/modules/girder/images/README.adoc diff --git a/contribute/modules/girder/README.adoc b/contribute/modules/girder/README.adoc new file mode 100644 index 00000000..7b87f3cd --- /dev/null +++ b/contribute/modules/girder/README.adoc @@ -0,0 +1 @@ +include::data:ROOT:partial$girder/README.adoc[] \ No newline at end of file diff --git a/contribute/modules/girder/images/README.adoc b/contribute/modules/girder/images/README.adoc deleted file mode 100644 index f39cf0fd..00000000 --- a/contribute/modules/girder/images/README.adoc +++ /dev/null @@ -1 +0,0 @@ -include::data:ROOT:partial$girder/README.adoc \ No newline at end of file From bb01cd3e75d591a1a303e7fbb5cfc2e208f03ba5 Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 11:25:28 +0200 Subject: [PATCH 6/9] #187 mv README.adoc into pages --- contribute/modules/girder/{ => pages}/README.adoc | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename contribute/modules/girder/{ => pages}/README.adoc (100%) diff --git a/contribute/modules/girder/README.adoc b/contribute/modules/girder/pages/README.adoc similarity index 100% rename from contribute/modules/girder/README.adoc rename to contribute/modules/girder/pages/README.adoc From f04740a0ea87396831ac50d6203922039996976a Mon Sep 17 00:00:00 2001 From: lberti Date: Mon, 4 Sep 2023 11:34:29 +0200 Subject: [PATCH 7/9] #187 add pages referring to partials --- contribute/modules/girder/pages/api_keys.adoc | 1 + contribute/modules/girder/pages/python_scripts.adoc | 1 + 2 files changed, 2 insertions(+) create mode 100644 contribute/modules/girder/pages/api_keys.adoc create mode 100644 contribute/modules/girder/pages/python_scripts.adoc diff --git a/contribute/modules/girder/pages/api_keys.adoc b/contribute/modules/girder/pages/api_keys.adoc new file mode 100644 index 00000000..959e2b4a --- /dev/null +++ b/contribute/modules/girder/pages/api_keys.adoc @@ -0,0 +1 @@ +include::data:ROOT:partial$girder/api_keys.adoc[] \ No newline at end of file diff --git a/contribute/modules/girder/pages/python_scripts.adoc b/contribute/modules/girder/pages/python_scripts.adoc new file mode 100644 index 00000000..f8f86185 --- /dev/null +++ b/contribute/modules/girder/pages/python_scripts.adoc @@ -0,0 +1 @@ +include::data:ROOT:partial$girder/python_scripts.adoc[] \ No newline at end of file From 13db2c1088b4a23525323d639b42352be4a5f4c8 Mon Sep 17 00:00:00 2001 From: lberti Date: Tue, 5 Sep 2023 09:24:00 +0200 Subject: [PATCH 8/9] #187 modify readme page --- contribute/modules/girder/pages/README.adoc | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/contribute/modules/girder/pages/README.adoc b/contribute/modules/girder/pages/README.adoc index 7b87f3cd..323f510b 100644 --- a/contribute/modules/girder/pages/README.adoc +++ b/contribute/modules/girder/pages/README.adoc @@ -1 +1,13 @@ -include::data:ROOT:partial$girder/README.adoc[] \ No newline at end of file += Girder + +== What is Girder + +Girder is a data management platform. +It can be used to store (large) files such as meshes, simulation results, etc... +Read more about it in the {feelpp} xref:data:ROOT:data-storage.adoc[data manual] or +link:http://girder.readthedocs.io/[on the official website]. + +include::data:ROOT:partial$girder/README.adoc[] + +Let's check out some +xref:contribute:girder:python_scripts.adoc[scripts]. \ No newline at end of file From 51fdfc20a9931e0b0378b7aceaec0b2c1dc458ef Mon Sep 17 00:00:00 2001 From: lberti Date: Tue, 5 Sep 2023 10:13:15 +0200 Subject: [PATCH 9/9] #187 remove ref to python scripts --- contribute/modules/girder/pages/README.adoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/contribute/modules/girder/pages/README.adoc b/contribute/modules/girder/pages/README.adoc index 323f510b..0530e43c 100644 --- a/contribute/modules/girder/pages/README.adoc +++ b/contribute/modules/girder/pages/README.adoc @@ -7,7 +7,4 @@ It can be used to store (large) files such as meshes, simulation results, etc... Read more about it in the {feelpp} xref:data:ROOT:data-storage.adoc[data manual] or link:http://girder.readthedocs.io/[on the official website]. -include::data:ROOT:partial$girder/README.adoc[] - -Let's check out some -xref:contribute:girder:python_scripts.adoc[scripts]. \ No newline at end of file +include::data:ROOT:partial$girder/README.adoc[] \ No newline at end of file