Merge pull request #824 from globus/doc-flows-clients-sc-26305

Document Flows clients

docs/services/flows.rst

@@ -3,22 +3,55 @@ Globus Flows
 
 .. currentmodule:: globus_sdk
 
-.. autoclass:: FlowsClient
-   :members:
-   :member-order: bysource
-   :show-inheritance:
-   :exclude-members: error_class
+The Flows service allows users to create automation workflows (or, simply, "flows").
+When a flow is started, it must be authorized to perform actions on the user's behalf.
 
-.. autoclass:: SpecificFlowClient
-   :members:
-   :member-order: bysource
-   :show-inheritance:
-   :exclude-members: error_class
+Because a running flow (or, simply, a "run") can perform actions on the user's behalf,
+the Globus SDK has two client classes that can interact with the Flows service:
+a :class:`FlowsClient` and a :class:`SpecificFlowClient`.
+They differ in what operations they can perform and, as a result,
+what scopes they require:
+
+*   :class:`FlowsClient` is able to create, update, and delete flows.
+    It is also able to retrieve information about flows and runs.
+
+    Users must consent to allow the client application to administer flows and runs.
+    See :class:`FlowsClient.scopes` for a complete list of scopes.
+
+*   :class:`SpecificFlowClient` must be instantiated with a specific flow ID
+    so it can construct the scope associated with the flow.
+    It is then able to start that specific flow.
+    If a run associated with the flow becomes inactive for any reason,
+    it is able to resume the run, too.
+
+    Users must consent to allow the specific flow to perform actions on their behalf.
+    The specific flow scope can be accessed via ``SpecificFlowClient.scopes.user``
+    after the :class:`SpecificFlowClient` has been instantiated.
+
+Applications that create and then start a flow would therefore need to use both classes.
+
+
+..  autoclass:: FlowsClient
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+    :exclude-members: error_class, scopes
+
+    ..  attribute:: scopes
+
+        ..  listknownscopes:: globus_sdk.scopes.FlowsScopes
+            :base_name: FlowsClient.scopes
+
+..  autoclass:: SpecificFlowClient
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+    :exclude-members: error_class
 
 Client Errors
 -------------
 
-When an error occurs, a :class:`FlowsClient` will raise a `FlowsAPIError`.
+When an error occurs, a :class:`FlowsClient` will raise a ``FlowsAPIError``.
 
 .. autoclass:: FlowsAPIError
    :members:

src/globus_sdk/_sphinxext.py

@@ -123,11 +123,17 @@ class ListKnownScopes(AddContentDirective):
     has_content = False
     required_arguments = 1
     optional_arguments = 0
-    option_spec = {"example_scope": directives.unchanged}
+    option_spec = {
+        "example_scope": directives.unchanged,
+        # Allow overriding the base name to match how the ScopeBuilder will be accessed.
+        "base_name": directives.unchanged,
+    }
 
     def gen_rst(self):
         sb_name = self.arguments[0]
         sb_basename = sb_name.split(".")[-1]
+        if "base_name" in self.options:
+            sb_basename = self.options["base_name"]
 
         example_scope = None
         if "example_scope" in self.options:

src/globus_sdk/services/flows/client.py

@@ -820,7 +820,7 @@ class SpecificFlowClient(client.BaseClient):
     Client for interacting with a specific Globus Flow through the Flows API.
 
     Unlike other client types, this must be provided with a specific flow id. All other
-        arguments are the same as those for `~globus_sdk.BaseClient`.
+        arguments are the same as those for :class:`~globus_sdk.BaseClient`.
 
     :param flow_id: The generated UUID associated with a flow
     :type flow_id: str or uuid