doc: add basic documentation

Author: azmeuk

README.md

@@ -55,7 +55,7 @@ Check the [reference](https://scim2-cli.readthedocs.io/en/latest/reference.html)
 Here is an example of resource creation:
 
 ```shell
-$ scim2 https://auth.example --headers "Authorization: Bearer 12345" create user --user-name "[email protected]"
+$ scim2 --url https://auth.example --header "Authorization: Bearer 12345" create user --user-name "[email protected]"
 {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id": "2819c223-7f76-453a-919d-413861904646",
@@ -73,7 +73,7 @@ $ scim2 https://auth.example --headers "Authorization: Bearer 12345" create user
 Here is an example of resource query:
 
 ```shell
-$ scim2 https://auth.example --header "Authorization: Bearer 12345" query user 2819c223-7f76-453a-919d-413861904646
+$ scim2 --url https://auth.example --header "Authorization: Bearer 12345" query user 2819c223-7f76-453a-919d-413861904646
 {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id": "2819c223-7f76-453a-919d-413861904646",

doc/index.rst

@@ -7,6 +7,7 @@ Table of contents
 .. toctree::
     :maxdepth: 2
 
+    tutorial
     reference
     contributing
     changelog

doc/tutorial.rst

@@ -0,0 +1,47 @@
+Tutorial
+========
+
+The :ref:`cli` command allows you to interact with a SCIM server.
+
+Basic parameters
+----------------
+
+In order to connect to a SCIM server you will need to pass the :option:`scim --url` parameter.
+You can also pass additional headers, such as authentication ones, with :option:`scim --url`.
+
+.. code-block:: shell
+
+    $ scim2 --url https://auth.example --header "Authorization: Bearer 12345" create user --user-name "[email protected]"
+    {
+        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+        "id": "2819c223-7f76-453a-919d-413861904646",
+        "userName": "[email protected]",
+        "meta": {
+            "resourceType": "User",
+            "created": "2010-01-23T04:56:22Z",
+            "lastModified": "2011-05-13T04:42:34Z",
+            "version": 'W\\/"3694e05e9dff590"',
+            "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
+        },
+    }
+
+However passing those parameters each time you use the command can be annoying.
+To make commands shorter, you can set those parameters once for all by using the :ref:`SCIM_CLI_URL <scim-url-scim_cli_url>` and :ref:`SCIM_CLI_HEADERS <scim-header-scim_cli_headers>` environment vars.
+
+.. code-block:: shell
+
+    $ export SCIM_CLI_URL="https://auth.example"
+    $ export SCIM_CLI_HEADERS="Authorization: Bearer 12345"
+    $ scim2 create user --user-name "[email protected]"
+    {
+        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+        "id": "2819c223-7f76-453a-919d-413861904646",
+        "userName": "[email protected]",
+        "meta": {
+            "resourceType": "User",
+            "created": "2010-01-23T04:56:22Z",
+            "lastModified": "2011-05-13T04:42:34Z",
+            "version": 'W\\/"3694e05e9dff590"',
+            "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
+        },
+    }

scim2_cli/create.py

@@ -52,21 +52,21 @@ def create_command(ctx, indent, obj: model, *args, **kwargs):
 
         .. code-block:: bash
 
-            scim https://scim.example create user --user-name "foo" --name-given-name "bar"
+            scim create user --user-name "foo" --name-given-name "bar"
 
         Multiple attributes should be passed as JSON payloads:
 
         .. code-block:: bash
 
-            scim https://scim.example create user \\
+            scim create user \\
                 --user-name "foo" \\
                 --emails '[{"value":"[email protected]", "primary": true}, {"value": "[email protected]"}]'
 
         Input can also be passed through stdin in JSON format:
 
         .. code-block:: bash
 
-            echo '{"userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' | scim https://scim.example create user
+            echo '{"userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' |  create user
 
         """
         if obj == model():
@@ -103,13 +103,13 @@ def create_cli(ctx, indent):
 
     .. code-block:: bash
 
-        scim https://scim.example create user --help
+         create user --help
 
     If no subcommand is executed, input data is expected to be passed in JSON format to stdin:
 
     .. code-block:: bash
 
-        echo '{"userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' | scim https://scim.example create
+        echo '{"userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' |  create
 
     """
     if ctx.invoked_subcommand is not None:

scim2_cli/delete.py

@@ -26,7 +26,7 @@ def delete_cli(ctx, resource_type, id, indent):
 
     .. code-block:: bash
 
-        scim https://scim.example delete user 1234
+         delete user 1234
     """
     try:
         resource_model = ctx.obj["resource_models"][resource_type]

scim2_cli/query.py

@@ -74,7 +74,7 @@ def query_cli(
 
     .. code-block:: bash
 
-        echo '{"startIndex": 50, "count": 10}' | scim https://scim.example query user
+        echo '{"startIndex": 50, "count": 10}' |  query user
 
     """
     if resource_type:

scim2_cli/replace.py

@@ -53,13 +53,13 @@ def replace_command(ctx, indent, obj: model, *args, **kwargs):
 
         .. code-block:: bash
 
-            scim https://scim.example replace user --id "xxxx-yyyy" --user-name "foo" --name-given-name "bar"
+             replace user --id "xxxx-yyyy" --user-name "foo" --name-given-name "bar"
 
         Multiple attributes should be passed as JSON payloads:
 
         .. code-block:: bash
 
-            scim https://scim.example replace user \\
+             replace user \\
                 --id "xxxx-yyyy" \\
                 --user-name "foo" \\
                 --emails '[{"value":"[email protected]", "primary": true}, {"value": "[email protected]"}]'
@@ -68,7 +68,7 @@ def replace_command(ctx, indent, obj: model, *args, **kwargs):
 
         .. code-block:: bash
 
-            echo '{"id": "xxxx-yyyy", "userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' | scim https://scim.example replace user
+            echo '{"id": "xxxx-yyyy", "userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' |  replace user
 
         """
         if obj == model():
@@ -109,13 +109,13 @@ def replace_cli(ctx, indent):
 
     .. code-block:: bash
 
-        scim https://scim.example replace user --help
+         replace user --help
 
     If no subcommand is executed, input data is expected to be passed in JSON format to stdin:
 
     .. code-block:: bash
 
-        echo '{"userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1234"}' | scim https://scim.example replace user
+        echo '{"userName": "[email protected]", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1234"}' |  replace user
 
     """
     if ctx.invoked_subcommand is not None:

scim2_cli/search.py

@@ -66,7 +66,7 @@ def search_cli(
 
     .. code-block:: bash
 
-        echo '{"startIndex": 50, "count": 10}' | scim https://scim.example search user
+        echo '{"startIndex": 50, "count": 10}' |  search user
 
     """
     if ctx.obj.get("stdin"):

scim2_cli/test.py

@@ -15,7 +15,7 @@ def test_cli(ctx, verbose):
 
     .. code-block:: bash
 
-        scim https://scim.example test
+         test
     """
     client = ctx.obj["client"]
     results = check_server(client)