ARLAS CLI Documentation #22

WilliGautier · 2024-10-08T14:01:41Z

No description provided.

docs/docs/collections.md

docs/docs/index.md

sylvaingaudan · 2024-11-04T16:38:20Z

docs/docs/index.md

@@ -2,6 +2,21 @@

 __ARLAS Exploration__ is an Open Source software for exploring and analysing Geo BigData. __ARLAS Command Line__ (`arlas_cli`) is for managing elasticsearch indices, ARLAS collections and elasticsearch/ARLAS endpoint configurations.

+
+TODO: Definition of concepts and schema, at least:


Not in this page. You could create a page "Concepts" and put all definitions theres, and make some links from this page to the concepts page. Keep this page readable in 5 mins

sylvaingaudan · 2024-11-04T16:40:04Z

docs/docs/indices.md

+    Make sure to take enough rows into account to get all the fields with the option `--nb_lines`
+
+!!! tip
+    For NDJSON files generated with Apache Spark, files are often partitioned into several parts into a `data.json` folder:


Many tools generate many files, no need to mention Apache Spark here.

sylvaingaudan · 2024-11-04T16:42:09Z

docs/docs/collections.md

+
+!!! warning "--owner"
+
+    It is mandatory to associate an organisation to a collection.


actually, it is not mandatory (some deployment do not use arlas iam).
also, arlas cli provide the one from the conf file, so you do not have to provide it.

The collection can be associated to an organisation. Example: `--owner your.organisation.com` By default, the organisation referenced in your `config` is used as owner.

Ok?

sylvaingaudan · 2024-11-04T17:16:37Z

docs/docs/configuration.md

+
+## Configure arlas_cli for ARLAS Cloud
+
+To configure `arlas_cli` for your cloud.arlas.io account:


I believe that this is quite important and that having a dedicated page was a good way to spot it. If you put it in this big file, then it must be more highlighted

sylvaingaudan · 2024-11-04T17:18:00Z

docs/docs/indices.md

+
+## Elasticsearch index
+
+ARLAS rely on [elasticsearch](https://www.elastic.co/fr/elasticsearch), an open-source search engine to perform quick aggregation requests over data.


You could move this in the "concepts" page and add a link here.

sylvaingaudan · 2024-11-04T17:19:21Z

docs/docs/indices.md

+
+Once you're happy with the mapping, you can either store it in a file or directly push it on elasticsearch.
+
+!!! tip "Store mapping in a file"


we do not have to teach how to redirect the content in a file. I would remove this "tip"

As we have the command create that rely on a mapping file, it can be usefull to explain how to easily create a mapping file no?

sylvaingaudan · 2024-11-04T17:21:47Z

docs/docs/install.md


 ## Install

+### Python Virtual environment


Move ### Python Virtual environment after ### Install arlas_cli

Even if the pip install is advised to be done in a virtual env?

I believe this is recommended for packages within a python project, not necessarily for a global shell command line.

Yes except in windows where it has to be in a virtual env, but you're right I can put it after and add a simple warning for windows users

sylvaingaudan · 2024-11-04T17:23:01Z

docs/docs/install.md

+    ```
+
+    The version of `arlas_cli` is `X.Y.Z` where `X` is ARLAS Stack main version and `Y.Z` is the increment of arlas_cli version.
+


Here, we should speak about cloud.arlas.io and add a link to the configuration doc.

sylvaingaudan · 2024-11-14T06:53:00Z

README.md


 See the documentation at https://gisaia.github.io/arlas_cli/
+
+NB: To run the commands locally from the project root, simply replace `arlas_cli` by `python3.10 -m arlas.cli.cli`


they will install arlas cli, not clone the project. They will get confused with this.
We can add a "developper section" and provide that information if you believe that this is necessary.

sylvaingaudan · 2024-11-14T06:54:54Z

docs/docs/collections.md

+
+!!! note "--owner"
+
+    The collection can be associated to an organisation.


I would say instead:
"If ARLAS is used with ARLAS IAM (like ARLAS Cloud), then a collection must be associated ..."

sylvaingaudan · 2024-11-14T06:59:23Z

docs/docs/collections.md

+To set it with the `name` subcommand:
+```shell
+> arlas_cli  collections \
+   --config local \


here you choose a lot of default values, like local, collection_name, and so on. It is not easy to know which parameter the user is supposed to change. Can you fond a trick to highlight the values to be changed?

Good point, I added a {local} syntaxe for all that can be changed

sylvaingaudan · 2024-11-14T07:00:41Z

docs/docs/collections.md

+
+## set_alias
+
+The data fields are sometimes not very readable. You can set aliases to improve their display in the ARLAS Dashboards configuration.


"The data fields are sometimes not very suitable in ARLAS Exploration dashboards. You can set aliases to improve their display in the interface."

sylvaingaudan · 2024-11-14T07:01:22Z

docs/docs/collections.md

+```shell
+> arlas_cli collections --config local set_alias --help
+
+Usage: arlas_cli collections set_alias [OPTIONS] COLLECTION FIELD_PATH


this should be generated. But this is not necessary to list all the subcommands. This is going to be horrible to maintain.

sylvaingaudan · 2024-11-14T07:05:25Z

docs/docs/configuration.md

+
+You can also use the command line itself.
+
+!!! tip


I don't know if this is a good idea : it is so easy to mess up the file ...

If people want to, they can edit it, but yeah, we shouldn't tell them that they can/should

sylvaingaudan · 2024-11-14T07:07:35Z

docs/docs/confs.md

+    ...
+```
+
+TODO: Check: org filter:


sylvaingaudan · 2024-11-14T07:09:37Z

docs/docs/confs.md

+
+    The following options are used to create the conf:
+    ```
+    arlas_cli confs create


I do not think that this is a good idea to have partial commands. You can list the parameters if presenting it as a command is dangerous, people will copy paste.

sylvaingaudan · 2024-11-14T07:10:11Z

docs/docs/confs.md

+The ARLAS server url (`ARLAS_SERVER_URL`) and the persistence server URL (`ARLAS_PERSISTENCE_URL`) has to be set in the configuration:
+```
+arlas_cli confs create
+    ...


I do not think that this is a good idea to have partial commands. You can list the parameters if presenting it as a command is dangerous, people will copy paste.

sylvaingaudan · 2024-11-14T07:10:15Z

docs/docs/confs.md

+The following options are used to create the conf:
+```
+arlas_cli confs create
+    ...


I do not think that this is a good idea to have partial commands. You can list the parameters if presenting it as a command is dangerous, people will copy paste.

docs/docs/collections.md

QuCMGisaia · 2024-11-14T09:01:26Z

docs/docs/collections.md

+
+The collection has to reference an ES index available with the [arlas_cli conf](confs.md#configurations).
+
+The index option set the targeted index:`--index index_name`


If kept in the doc: set -> sets

docs/docs/collections.md

docs/docs/started.md

docs/docs/collections.md

docs/docs/confs.md

templates for help

…tation # Conflicts: # docs/docs/collections.md # docs/docs/confs.md # docs/docs/indices.md # docs/docs/persist.md

WilliGautier added the documentation Improvements or additions to documentation label Oct 8, 2024

WilliGautier requested a review from sylvaingaudan October 8, 2024 14:01

WilliGautier self-assigned this Oct 8, 2024

WilliGautier force-pushed the feat/update_documentation branch 2 times, most recently from 66a3518 to 9c5662e Compare November 4, 2024 16:50

sylvaingaudan reviewed Nov 4, 2024

View reviewed changes

Update arlas_cli documentation

b272863

WilliGautier force-pushed the feat/update_documentation branch from 9c5662e to b272863 Compare November 13, 2024 17:17

Fix comments and update arlas_cli documentation

6af6a73

WilliGautier requested a review from QuCMGisaia November 13, 2024 17:25

WilliGautier changed the title ~~WIP~~ ARLAS CLI Documentation Nov 13, 2024

sylvaingaudan reviewed Nov 14, 2024

View reviewed changes

Fix comments and update arlas_cli documentation

3faf8d1

QuCMGisaia reviewed Nov 14, 2024

View reviewed changes

docs/docs/collections.md Outdated Show resolved Hide resolved

docs/docs/confs.md Outdated Show resolved Hide resolved

sylvaingaudan force-pushed the feat/update_documentation branch from 3faf8d1 to 1fb33b6 Compare November 15, 2024 13:11

Add elements in concepts page

8ce5cd1

WilliGautier force-pushed the feat/update_documentation branch from 1fb33b6 to 8ce5cd1 Compare November 15, 2024 17:34

sylvaingaudan and others added 6 commits November 17, 2024 19:17

templates for help

e0f13aa

Merge pull request #39 from gisaia/feat/template

c3d6779

templates for help

Merge remote-tracking branch 'origin/master' into feat/update_documen…

df72505

…tation # Conflicts: # docs/docs/collections.md # docs/docs/confs.md # docs/docs/indices.md # docs/docs/persist.md

Fix images display

015b5f3

Documentation feedbacks

0a6cbe9

Add arlas_cli login documentation

05b33b5

WilliGautier force-pushed the feat/update_documentation branch from cbd5ef4 to 05b33b5 Compare November 18, 2024 11:20

sylvaingaudan merged commit 40461a9 into master Nov 18, 2024
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ARLAS CLI Documentation #22

ARLAS CLI Documentation #22

WilliGautier commented Oct 8, 2024

sylvaingaudan Nov 4, 2024

sylvaingaudan Nov 4, 2024

sylvaingaudan Nov 4, 2024

WilliGautier Nov 5, 2024

sylvaingaudan Nov 4, 2024

sylvaingaudan Nov 4, 2024

sylvaingaudan Nov 4, 2024

WilliGautier Nov 5, 2024

sylvaingaudan Nov 4, 2024

WilliGautier Nov 6, 2024

sylvaingaudan Nov 6, 2024 •

edited

Loading

WilliGautier Nov 6, 2024

sylvaingaudan Nov 4, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

WilliGautier Nov 14, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

QuCMGisaia Nov 14, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

sylvaingaudan Nov 14, 2024

QuCMGisaia Nov 14, 2024

		@@ -2,6 +2,21 @@

		__ARLAS Exploration__ is an Open Source software for exploring and analysing Geo BigData. __ARLAS Command Line__ (`arlas_cli`) is for managing elasticsearch indices, ARLAS collections and elasticsearch/ARLAS endpoint configurations.


		TODO: Definition of concepts and schema, at least:


		!!! warning "--owner"

		It is mandatory to associate an organisation to a collection.


		## Configure arlas_cli for ARLAS Cloud

		To configure `arlas_cli` for your cloud.arlas.io account:


		## Elasticsearch index

		ARLAS rely on [elasticsearch](https://www.elastic.co/fr/elasticsearch), an open-source search engine to perform quick aggregation requests over data.


		Once you're happy with the mapping, you can either store it in a file or directly push it on elasticsearch.

		!!! tip "Store mapping in a file"

		```

		The version of `arlas_cli` is `X.Y.Z` where `X` is ARLAS Stack main version and `Y.Z` is the increment of arlas_cli version.


		See the documentation at https://gisaia.github.io/arlas_cli/

		NB: To run the commands locally from the project root, simply replace `arlas_cli` by `python3.10 -m arlas.cli.cli`


		!!! note "--owner"

		The collection can be associated to an organisation.


		## set_alias

		The data fields are sometimes not very readable. You can set aliases to improve their display in the ARLAS Dashboards configuration.


		The collection has to reference an ES index available with the [arlas_cli conf](confs.md#configurations).

		The index option set the targeted index:`--index index_name`

ARLAS CLI Documentation #22

ARLAS CLI Documentation #22

Conversation

WilliGautier commented Oct 8, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sylvaingaudan Nov 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sylvaingaudan Nov 6, 2024 •

edited

Loading