Update language

devintyler · web-flow · commit 8662e428f098 · 2016-08-16T11:24:19.000-04:00
diff --git a/docs/source/custom_sockets.rst b/docs/source/custom_sockets.rst
@@ -4,23 +4,23 @@
 Custom Sockets in Syncano
 =========================
 
-``Syncano`` gives its users an ability to create Custom Sockets. What it means is that users can define 
-a very specific endpoints in their Syncano application, and use them exactly like they would any other Syncano 
+``Syncano`` gives its users the ability to create Custom Sockets. What this means is that users can define very specific
+endpoints in their Syncano application, and use them exactly like they would any other Syncano 
 module (Classes, Scripts, etc), using standard API calls.
-Currently, Custom Sockets allow only one dependency - Scripts. It means that under the hood,
-each API call executes a Script, and result of this execution is returned as a result of the
+Currently, Custom Sockets allow only one dependency - Scripts. Under the hood,
+each API call executes a Script, and the result of this execution is returned as a result of the
 API call.
 
-Creating a custom socket
+Creating a custom Socket
 ------------------------
 
-To create a custom socket follow these steps::
+To create a custom Socket follow these steps::
 
     import syncano
     from syncano.models import CustomSocket, Endpoint, ScriptCall, ScriptDependency, RuntimeChoices
     from syncano.connection import Connection
 
-    # 1. Initialize a custom socket.
+    # 1. Initialize a custom Socket.
     custom_socket = CustomSocket(name='my_custom_socket')  # this will create an object in place (do API call)
 
     # 2. Define endpoints.
@@ -29,28 +29,28 @@ To create a custom socket follow these steps::
     my_endpoint.add_call(ScriptCall(name='another_custom_script'), methods=['POST'])
 
     # What happened here:
-    # - We defined a new endpoint, that will be visible under `my_endpoint` name.
+    # - We defined a new endpoint that will be visible under the name `my_endpoint`
     # - You will be able to call this endpoint (execute attached `call`), 
-    # by sending a reuqest, using any defined method to following API route:
+    # by sending a request, using any defined method to the following API route:
     # <host>://<api_version>/instances/<instance_name>/endpoints/sockets/my_endpoint/ 
-    # - To get details on that endpoint, you need to send a GET request to following API route:
+    # - To get details for that endpoint, you need to send a GET request to following API route:
     # <host>://<api_version>/instances/<instance_name>/sockets/my_custom_socket/endpoints/my_endpoint/
     #
-    # Following example above - we defined two calls on our endpoint. 
-    # First one means that using GET method will call the `custom_script` script,
-    # and second one means that using POST method will call the `another_custom_script` script.
-    # At the moment, only scripts are available as endpoint calls.
+    # Following the example above - we defined two calls on our endpoint with the `add_call` method
+    # The first one means that using a GET method will call the `custom_script` Script,
+    # and second one means that using a POST method will call the `another_custom_script` Script.
+    # At the moment, only Scripts are available as endpoint calls.
     #
-    # As a general rule - to get endpoints details (but not call them), use following API route:
+    # As a general rule - to get endpoint details (but not call them), use following API route:
     # <host>://<api_version>/instances/<instance_name>/sockets/my_custom_socket/endpoints/<endpoint>/
-    # and to run your endpoints (e.g. execute Script connected to them(, use following API route:
+    # and to run your endpoints (e.g. execute Script connected to them), use following API route:
     # <host>://<api_version>/instances/<instance_name>/endpoints/sockets/<endpoint>/
 
     # 3. After creation of the endpoint, add it to your custom_socket.
     custom_socket.add_endpoint(my_endpoint)
 
     # 4. Define dependency.
-    # 4.1 Using a new script - define a new source code.
+    # 4.1 Using a new Script - define a new source code.
     custom_socket.add_dependency(
         ScriptDependency(
             Script(
@@ -60,7 +60,7 @@ To create a custom socket follow these steps::
             name='custom_script'
         )
     )
-    # 4.2 Using an existing script.
+    # 4.2 Using an existing Script.
     another_custom_script = Script.please.get(id=2)
     custom_socket.add_dependency(
         ScriptDependency(
@@ -78,19 +78,19 @@ To create a custom socket follow these steps::
     # 5. Publish custom_socket.
     custom_socket.publish()  # this will make an API call and create a script;
 
-Sometimes, it's needed to set up the environment for the custom socket.
-It's possible to check the custom socket status::
+It may take some time to set up the Socket, so you can check the status.
+It's possible to check the custom Socket status::
 
     # Reload will refresh object using Syncano API.
     custom_socket.reload()
     print(custom_socket.status)
     # and
     print(custom_socket.status_info)
 
-Updating the custom socket
+Updating the custom Socket
 --------------------------
 
-To update custom socket, use::
+To update custom Socket, use::
 
     custom_socket = CustomSocket.please.get(name='my_custom_socket')
 
@@ -109,19 +109,19 @@ To update custom socket, use::
     custom_socket.update()
 
 
-Running custom socket
+Running custom Socket
 -------------------------
 
-To run a custom socket use::
+To run a custom Socket use::
 
-    # this will run `my_endpoint` - and call `custom_script` (using GET method);
+    # this will run `my_endpoint` - and call `custom_script` using GET method;
     result = custom_socket.run(method='GET', endpoint_name='my_endpoint')
 
 
-Read all endpoints in a custom socket
+Read all endpoints in a custom Socket
 -----------------------------------
 
-To get the all defined endpoints in a custom socket run::
+To get the all defined endpoints in a custom Socket run::
 
     endpoints = custom_socket.get_endpoints()
 
@@ -140,7 +140,7 @@ Data will be passed to the API call in the request body.
 Read all endpoints
 ------------------
 
-To get all endpoints that are defined in all custom sockets::
+To get all endpoints that are defined in all custom Sockets::
 
     socket_endpoint_list = SocketEndpoint.get_all_endpoints()
 
@@ -155,15 +155,15 @@ and now run it::
     # or:
     endpoint.run(method='POST', data={'custom_data': 1})
 
-Custom sockets endpoints
+Custom Sockets endpoints
 ------------------------
 
-Each custom socket requires a definition of at least one endpoint. This endpoint is defined by name and
-a list of calls.  Each call is defined by its name and a list of methods. Name is used in identification for dependency, eg.
-if it's equal to 'my_script' - the ScriptEndpoint with name 'my_script' will be used
-(if it exists and Script source and passed runtime match) -- otherwise a new one will be created.
-There's a special wildcard method: `methods=['*']` - it means that any request with
-any method will be executed in this endpoint.
+Each custom socket requires defining at least one endpoint. This endpoint is defined by name and
+a list of calls. Each call is defined by its name and a list of methods. `name` is used as an
+identification for the dependency, eg. if `name` is equal to 'my_script' - the ScriptEndpoint with name 'my_script'
+will be used (if it exists and Script source and passed runtime match) -- otherwise a new one will be created.
+There's a special wildcard method: `methods=['*']` - this allows you to execute the provided custom Socket
+with any request method (GET, POST, PATCH, etc.).
 
 To add an endpoint to a chosen custom_socket use::
 
@@ -173,14 +173,14 @@ To add an endpoint to a chosen custom_socket use::
 
     custom_socket.add_endpoint(my_endpoint)
 
-Custom socket dependency
+Custom Socket dependency
 ------------------------
 
 Each custom socket has a dependency -- meta information for an endpoint: which resource
-should be used to return the API call results. These dependencies are bound to the endpoints call objects.
+should be used to return the API call results. These dependencies are bound to the endpoints call object.
 Currently the only supported dependency is a Script.
 
-**Using new script**
+**Using new Script**
 
 ::
 
@@ -195,7 +195,7 @@ Currently the only supported dependency is a Script.
     )
 
 
-**Using defined script**
+**Using defined Script**
 
 ::
 
@@ -207,7 +207,7 @@ Currently the only supported dependency is a Script.
         )
     )
 
-**Using defined script endpoint**
+**Using defined Script endpoint**
 
 ::
 
@@ -216,31 +216,31 @@ Currently the only supported dependency is a Script.
         script_endpoint
     )
 
-You can overwrite the name in the following way::
+You can overwrite the Script name in the following way::
 
     script_endpoint = ScriptEndpoint.please.get(name='script_endpoint_name')
     custom_socket.add_dependency(
         script_endpoint,
         name='custom_name'
     )
 
-Custom socket recheck
+Custom Socket recheck
 ---------------------
 
-The creation of the socket can fail - this can happen, e.g. when an endpoint name is already taken by another
-custom socket. To check the statuses use::
+The creation of a Socket can fail - this can happen, for example, when an endpoint name is already taken by another
+custom Socket. To check the creation status use::
 
     print(custom_socket.status)
     print(custom_socket.status_info)
 
-There is a possibility to re-check socket - this mean that if conditions are met - the socket endpoints and dependencies
-will be checked - and if some of them are missing (e.g. some were deleted by mistake), they will be created again.
-If the endpoints and dependencies do not meet the criteria - an error will be returned in the status field.
+You can also re-check a Socket. This mean that all dependencies will be checked - if some of them are missing
+(e.g. some were deleted by mistake), they will be created again. If the endpoints and dependencies do not meet
+the criteria - an error will be returned in the status field.
 
-Custom socket - raw format
+Custom Socket - raw format
 --------------------------
 
-If you prefer raw JSON format for creating sockets, you can resort to use it in python library as well::::
+If you prefer raw JSON format for creating Sockets, the Python library allows you to do so::::
 
     CustomSocket.please.create(
         name='my_custom_socket_3',
@@ -262,4 +262,4 @@ If you prefer raw JSON format for creating sockets, you can resort to use it in
         ]
     )
 
-The disadvantage of this method is that internal structure of the JSON file must be known by developer.
+The disadvantage of this method is that the internal structure of the JSON file must be known by the developer.
