[Google] Updated documentation of Google plugins.

Expanded explanation of the desktop vs. headless authentication process
and where the credential files are supposed to be copied if the user
opts for a non-automatic authentication flow.

platypush/plugins/google/__init__.py

@@ -29,15 +29,36 @@ class GooglePlugin(Plugin):
         5 Select "Desktop app", enter whichever name you like, and click "Create".
 
         6. Click on the "Download JSON" icon next to your newly created client ID.
+           Save the JSON file under
+           ``<WORKDIR>/credentials/google/client_secret.json``.
 
-        7. Generate a credentials file for the required scope:
+        7.1. If you're running the service on a desktop environment, then you
+             can just start the application. A browser window will open and
+             you'll be asked to authorize the application - you may be prompted
+             with a warning because you are running a personal and potentially
+             unverified application. After authorizing the application, the
+             process will save the credentials under
+             ``<WORKDIR>/credentials/google/<list,of,scopes>.json`` and proceed
+             with the plugin initialization.
 
-            .. code-block:: bash
+        7.2. If you're running the service on a headless environment, or you
+             prefer to manually generate the credentials file before copying to
+             another machine, you can run the following command:
 
-              mkdir -p <WORKDIR>/credentials/google
-              python -m platypush.plugins.google.credentials \
-                  'calendar.readonly' \
-                  <WORKDIR>/credentials/google/client_secret.json
+               .. code-block:: bash
+
+                  mkdir -p <WORKDIR>/credentials/google
+                  python -m platypush.plugins.google.credentials \
+                      'calendar.readonly,gmail.modify' \
+                      [--noauth_local_webserver] \
+                      <WORKDIR>/credentials/google/client_secret.json
+
+             When launched with ``--noauth_local_webserver``, the script will
+             start a local webserver and print a URL that should be opened in
+             your browser. After authorizing the application, you may be
+             prompted with a code that you should copy and paste back to the
+             script. Otherwise, if you're running the script on a desktop, a
+             browser window will be opened automatically.
 
     """
 

platypush/plugins/google/calendar/__init__.py

@@ -28,15 +28,36 @@ class GoogleCalendarPlugin(GooglePlugin, CalendarInterface):
         5 Select "Desktop app", enter whichever name you like, and click "Create".
 
         6. Click on the "Download JSON" icon next to your newly created client ID.
+           Save the JSON file under
+           ``<WORKDIR>/credentials/google/client_secret.json``.
 
-        7. Generate a credentials file for the required scope:
+        7.1. If you're running the service on a desktop environment, then you
+             can just start the application. A browser window will open and
+             you'll be asked to authorize the application - you may be prompted
+             with a warning because you are running a personal and potentially
+             unverified application. After authorizing the application, the
+             process will save the credentials under
+             ``<WORKDIR>/credentials/google/<list,of,scopes>.json`` and proceed
+             with the plugin initialization.
 
-            .. code-block:: bash
+        7.2. If you're running the service on a headless environment, or you
+             prefer to manually generate the credentials file before copying to
+             another machine, you can run the following command:
 
-              mkdir -p <WORKDIR>/credentials/google
-              python -m platypush.plugins.google.credentials \
-                  'calendar.readonly' \
-                  <WORKDIR>/credentials/google/client_secret.json
+                .. code-block:: bash
+
+                  mkdir -p <WORKDIR>/credentials/google
+                  python -m platypush.plugins.google.credentials \
+                      'calendar.readonly' \
+                      [--noauth_local_webserver] \
+                      <WORKDIR>/credentials/google/client_secret.json
+
+             When launched with ``--noauth_local_webserver``, the script will
+             start a local webserver and print a URL that should be opened in
+             your browser. After authorizing the application, you may be
+             prompted with a code that you should copy and paste back to the
+             script. Otherwise, if you're running the script on a desktop, a
+             browser window will be opened automatically.
 
     """
 

platypush/plugins/google/drive/__init__.py

@@ -28,15 +28,36 @@ class GoogleDrivePlugin(GooglePlugin):
         5 Select "Desktop app", enter whichever name you like, and click "Create".
 
         6. Click on the "Download JSON" icon next to your newly created client ID.
+           Save the JSON file under
+           ``<WORKDIR>/credentials/google/client_secret.json``.
 
-        7. Generate a credentials file for the required scope:
+        7.1. If you're running the service on a desktop environment, then you
+             can just start the application. A browser window will open and
+             you'll be asked to authorize the application - you may be prompted
+             with a warning because you are running a personal and potentially
+             unverified application. After authorizing the application, the
+             process will save the credentials under
+             ``<WORKDIR>/credentials/google/<list,of,scopes>.json`` and proceed
+             with the plugin initialization.
 
-            .. code-block:: bash
+        7.2. If you're running the service on a headless environment, or you
+             prefer to manually generate the credentials file before copying to
+             another machine, you can run the following command:
 
-              mkdir -p <WORKDIR>/credentials/google
-              python -m platypush.plugins.google.credentials \
-                  'drive,drive.appfolder,drive.photos.readonly' \
-                  <WORKDIR>/credentials/google/client_secret.json
+                .. code-block:: bash
+
+                  mkdir -p <WORKDIR>/credentials/google
+                  python -m platypush.plugins.google.credentials \
+                      'drive,drive.appfolder,drive.photos.readonly' \
+                      [--noauth_local_webserver] \
+                      <WORKDIR>/credentials/google/client_secret.json
+
+             When launched with ``--noauth_local_webserver``, the script will
+             start a local webserver and print a URL that should be opened in
+             your browser. After authorizing the application, you may be
+             prompted with a code that you should copy and paste back to the
+             script. Otherwise, if you're running the script on a desktop, a
+             browser window will be opened automatically.
 
     """
 

platypush/plugins/google/fit/__init__.py

@@ -25,22 +25,43 @@ class GoogleFitPlugin(GooglePlugin):
         5 Select "Desktop app", enter whichever name you like, and click "Create".
 
         6. Click on the "Download JSON" icon next to your newly created client ID.
+           Save the JSON file under
+           ``<WORKDIR>/credentials/google/client_secret.json``.
 
-        7. Generate a credentials file for the required scope:
+        7.1. If you're running the service on a desktop environment, then you
+             can just start the application. A browser window will open and
+             you'll be asked to authorize the application - you may be prompted
+             with a warning because you are running a personal and potentially
+             unverified application. After authorizing the application, the
+             process will save the credentials under
+             ``<WORKDIR>/credentials/google/<list,of,scopes>.json`` and proceed
+             with the plugin initialization.
 
-            .. code-block:: bash
+        7.2. If you're running the service on a headless environment, or you
+             prefer to manually generate the credentials file before copying to
+             another machine, you can run the following command:
 
-              $ mkdir -p <WORKDIR>/credentials/google
-              $ roles="
-              fitness.activity.read,
-              fitness.body.read,
-              fitness.body_temperature.read,
-              fitness.heart_rate.read,
-              fitness.sleep.read,
-              fitness.location.read
-              "
-              $ python -m platypush.plugins.google.credentials "$roles" \
-                  <WORKDIR>/credentials/google/client_secret.json
+                .. code-block:: bash
+
+                  $ mkdir -p <WORKDIR>/credentials/google
+                  $ roles="
+                  fitness.activity.read,
+                  fitness.body.read,
+                  fitness.body_temperature.read,
+                  fitness.heart_rate.read,
+                  fitness.sleep.read,
+                  fitness.location.read
+                  "
+                  $ python -m platypush.plugins.google.credentials "$roles" \
+                      [--noauth_local_webserver] \
+                      <WORKDIR>/credentials/google/client_secret.json
+
+             When launched with ``--noauth_local_webserver``, the script will
+             start a local webserver and print a URL that should be opened in
+             your browser. After authorizing the application, you may be
+             prompted with a code that you should copy and paste back to the
+             script. Otherwise, if you're running the script on a desktop, a
+             browser window will be opened automatically.
 
     """
 

platypush/plugins/google/mail/__init__.py

@@ -37,15 +37,36 @@ class GoogleMailPlugin(GooglePlugin):
         5 Select "Desktop app", enter whichever name you like, and click "Create".
 
         6. Click on the "Download JSON" icon next to your newly created client ID.
+           Save the JSON file under
+           ``<WORKDIR>/credentials/google/client_secret.json``.
 
-        7. Generate a credentials file for the required scope:
+        7.1. If you're running the service on a desktop environment, then you
+             can just start the application. A browser window will open and
+             you'll be asked to authorize the application - you may be prompted
+             with a warning because you are running a personal and potentially
+             unverified application. After authorizing the application, the
+             process will save the credentials under
+             ``<WORKDIR>/credentials/google/<list,of,scopes>.json`` and proceed
+             with the plugin initialization.
 
-            .. code-block:: bash
+        7.2. If you're running the service on a headless environment, or you
+             prefer to manually generate the credentials file before copying to
+             another machine, you can run the following command:
 
-              mkdir -p <WORKDIR>/credentials/google
-              python -m platypush.plugins.google.credentials \
-                  'gmail.modify' \
-                  <WORKDIR>/credentials/google/client_secret.json
+                .. code-block:: bash
+
+                  mkdir -p <WORKDIR>/credentials/google
+                  python -m platypush.plugins.google.credentials \
+                      'gmail.modify' \
+                      [--noauth_local_webserver] \
+                      <WORKDIR>/credentials/google/client_secret.json
+
+             When launched with ``--noauth_local_webserver``, the script will
+             start a local webserver and print a URL that should be opened in
+             your browser. After authorizing the application, you may be
+             prompted with a code that you should copy and paste back to the
+             script. Otherwise, if you're running the script on a desktop, a
+             browser window will be opened automatically.
 
     """