From b5939ccd3de0dddba2ac9ab67fc5a9168c7aec12 Mon Sep 17 00:00:00 2001
From: Pavel Raiskup <praiskup@redhat.com>
Date: Sep 13 2022 23:17:57 +0000
Subject: python: more generic docs for Client initialization


Mention that copr_url= is the only mandatory field in the configuration,
and that there's the gssapi= token.

Reported to me by several folks around the LEAPP team, because they
needed access to the read-only part of the API from a publicly available
CI workers.

Merges: #2281

---

diff --git a/python/docs/client_v3/client_initialization.rst b/python/docs/client_v3/client_initialization.rst
index f1b0f3d..16bc8ca 100644
--- a/python/docs/client_v3/client_initialization.rst
+++ b/python/docs/client_v3/client_initialization.rst
@@ -1,11 +1,41 @@
 Client initialization
 =====================
 
-Before an API client can be used, it needs to be initialized with a configuration. There are several ways to do it.
-The most standard option is reading the ``~/.config/copr`` file and providing it to the ``Client`` class. Please read
-https://copr.fedorainfracloud.org/api/ for more information about API token.
+Before an API client can be used, it needs to be initialized with a
+configuration.  There are several ways to do it.  The most standard option is
+reading the ``~/.config/copr`` file and providing it to the ``Client`` class.
 
-::
+Such a configuration file typically has::
+
+    [copr-cli]
+    copr_url = https://copr.fedorainfracloud.org
+    username = coprusername
+    login = secretlogin
+    token = secrettoken
+    # expiration date: 2023-01-17
+
+To get your configuration file for the Fedora Copr instance, go to
+https://copr.fedorainfracloud.org/api/
+
+The only mandatory field though is ``copr_url``::
+
+    [copr-cli]
+    copr_url = https://copr.fedorainfracloud.org
+
+With such a simplified configuration, you can still do the read-only API
+queries that do not require user-authentication (listing projects, builds,
+etc.).
+
+Alternatively, the Copr server you work with might support GSSAPI
+authentication (Fedora Copr does).  To let the Client use your ``kinit``
+tokens, you need to enable GSSAPI authentication first::
+
+    [copr-cli]
+    copr_url = https://copr.fedorainfracloud.org
+    gssapi = true
+
+Having the config file prepared, you can finally use it for creating a
+``Client`` instance.  Just like::
 
     from copr.v3 import Client
     from pprint import pprint
@@ -17,7 +47,7 @@ https://copr.fedorainfracloud.org/api/ for more information about API token.
     {'copr_url': u'https://copr.fedorainfracloud.org',
      'login': u'secretlogin',
      'token': u'secrettoken',
-     'username': u'frostyx'}
+     'username': u'coprusername'}
 
 A different config file can be easily used by passing its path to ``create_from_config_file`` method.
 
@@ -34,7 +64,7 @@ passed to the ``Client`` constructor.
     config = {'copr_url': u'https://copr.fedorainfracloud.org',
               'login': u'secretlogin',
               'token': u'secrettoken',
-              'username': u'frostyx'}
+              'username': u'coprusername'}
 
     client = Client(config)
     assert client.config == config
@@ -53,7 +83,7 @@ Or even without configuration file.
     config = {'copr_url': u'https://copr.fedorainfracloud.org',
               'login': u'secretlogin',
               'token': u'secrettoken',
-              'username': u'frostyx'}
+              'username': u'coprusername'}
 
     build_proxy = BuildProxy(config)