incorporate doc feedback

Sage-Bionetworks · Jul 7, 2021 · 3e0b717 · 3e0b717
1 parent c43b113
commit 3e0b717
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 14 deletions.
diff --git a/docs/Credentials.rst b/docs/Credentials.rst
@@ -11,7 +11,7 @@ Use :code:`username` and :code:`password` to login as follows::
     import synapseclient
     syn = synapseclient.login("username", "password")
 
-Alternately you can login using a personal access token obtained from synapse.org under your Settings. Note that a token must minimally have the *view* scope to be used with the Synapse Python Client.
+Alternately you can login using a `personal access token <https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens>`__ token obtained from synapse.org under your Settings. Note that a token must minimally have the *view* scope to be used with the Synapse Python Client.
 
 ::
 
@@ -21,7 +21,7 @@ Use Environment Variable
 =========================
 
 Setting the :code:`SYNAPSE_AUTH_TOKEN` environment variable will allow you to login
-to Synapse with a personal access token.
+to Synapse with a `personal access token <https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens>`__
 
 The environment variable will take priority over credentials in the user's :code:`.synapseConfig` file
 or any credentials saved in a prior login using :code:`syn.login(rememberMe=True)`.

diff --git a/docs/news.rst b/docs/news.rst
@@ -9,38 +9,37 @@ Release Notes
 Highlights
 ----------
 
-- Added ability to :code:`syn.login()` without arguments if the :code:`SYNAPSE_AUTH_TOKEN` enviroment variable is set with a valid personal access token
+- Added ability to authenticate from a :code:`SYNAPSE_AUTH_TOKEN` enviroment variable set with a valid `personal access token <https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens>`__.
 
   .. code-block:: bash
 
-        # set environment variable for python
-        SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' python3
+        # e.g. set environment variable prior to invoking a Synapse command or running a program that uses synapseclient
+        SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' synapse <subcommand options>
 
-  .. code-block:: python3
+  The environment variable will take priority over credentials in the user's :code:`.synapseConfig` filej
+  or any credentials saved in a prior login using the remember me option.
 
-        import synapseclient
-        # login() will retrieve the personal access token from environment variable
-        syn = synapseclient.login()
-  The environment variable will take priority over credentials in the user's :code:`.synapseConfig` file
-  or any credentials saved in a prior login using :code:`syn.login(rememberMe=True)`.
+  See `here <Credentials.html#use-environment-variable>`__ for more details on usage.
 
 - Added ability to silence all console output.
 
   .. code-block:: bash
 
-        # Use the --silent option with any synapse subcommand, here it will suppress the download progress indicator
+        # from the command line, use the --silent option with any synapse subcommand, here it will suppress the download progress indicator
         synapse --silent get <synid>
 
   .. code-block:: python3
 
-        # Suppress output using a programatically instantiated Synapse instance
+        # from code using synapseclient, pass the silent option to the Synapse constructor
         import synapseclient
 
         syn = synapseclient.Synapse(silent=True)
         syn.login()
         syn.get(<synid>)
 
-- Improved robustness during downloads with unstable connections.
+- Improved robustness during downloads with unstable connections. Specifically the client will automatically recover
+  when encoutering some types of network errors that previously would have caused a download to start over as indicated by a
+  reset progress bar.
 
 
 Bug Fixes