Language updates

MariuszWisniewski · web-flow · commit 4e2ee332c17d · 2016-08-12T18:41:24.000-04:00
diff --git a/docs/source/custom_sockets.rst b/docs/source/custom_sockets.rst
@@ -4,10 +4,11 @@
 Custom Sockets in Syncano
 =========================
 
-``Syncano`` provides possibility of creating custom sockets. It means that there's a possibility
-to define a very specific endpoints in syncano application and use them as normal API calls.
-Currently custom sockets allow only one dependency - script. This mean that on the backend side
-each time the API is called - the script is executed and result from this script is returned as a result of the
+``Syncano`` gives its users an ability to create custom sockets. It means, that users can define 
+a very specific endpoints in their Syncano application, and use them as other Syncano 
+modules (Classes, Scripts, etc), using standard API calls.
+Currently, custom sockets allow only one dependency - Scripts. It means that on the backend side,
+each API call executes a Script and result of the execution, is returned as a result of the
 API call.
 
 Creating a custom socket
@@ -19,16 +20,16 @@ To create a custom socket follow these steps::
     from syncano.models import CustomSocket, Endpoint, ScriptCall, ScriptDependency, RuntimeChoices
     from syncano.connection import Connection
 
-    # 1. Initialize the 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.
-    my_endpoint = Endpoint(name='my_endpoint')  # again - no API call here
+    my_endpoint = Endpoint(name='my_endpoint')  # no API call here
     my_endpoint.add_call(ScriptCall(name='custom_script'), methods=['GET'])
     my_endpoint.add_call(ScriptCall(name='another_custom_script'), methods=['POST'])
 
-    # explanation for the above lines:
-    # The endpoint will be seen under `my_endpoint` name:
+    # Explanation of the above lines:
+    # Defined endpoint will be visible under `my_endpoint` name:
     # On this syncano API endpoint the above endpoint will be called (after custom socket creation)
     # <host>://<api_version>/instances/<instance_name>/endpoints/sockets/my_endpoint/
     # On this syncano API endpoint the details of the defined endpoint will be returned
@@ -37,11 +38,11 @@ To create a custom socket follow these steps::
     # there, second uses the POST method and then the another_custom_script will be called;
     # Currently only script are available for calls;
 
-    # 3. After the creation of the endpoint, add them to custom_socket.
+    # 3. After creation of the endpoint, add it to your custom_socket.
     custom_socket.add_endpoint(my_endpoint)
 
-    # 4. Define dependency now.
-    # 4.1 using a new script - defining new source code.
+    # 4. Define dependency.
+    # 4.1 Using a new script - define a new source code.
     custom_socket.add_dependency(
         ScriptDependency(
             name='custom_script'
@@ -51,7 +52,7 @@ To create a custom socket follow these steps::
             )
         )
     )
-    # 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(
@@ -60,19 +61,19 @@ To create a custom socket follow these steps::
         )
     )
 
-    # 4.3 using an existing ScriptEndpoint.
+    # 4.3 Using an existing ScriptEndpoint.
     script_endpoint = ScriptEndpoint.please.get(name='script_endpoint_name')
     custom_socket.add_dependency(
         script_endpoint=script_endpoint
     )
 
     # 5. Publish custom_socket.
-    custom_socket.publish()  # this will do an API call and will create script;
+    custom_socket.publish()  # this will make an API call and create a script;
 
-Some time is needed to setup the environment for this custom socket.
-There is possibility to check the custom socket status::
+Sometimes, it's needed to set up the environment for the custom socket.
+It's possible to check the custom socket status::
 
-    # Reload will refresh object using syncano API.
+    # Reload will refresh object using Syncano API.
     custom_socket.reload()
     print(custom_socket.status)
     # and
@@ -85,30 +86,34 @@ To update custom socket, use::
 
     custom_socket = CustomSocket.please.get(name='my_custom_socket')
 
+    # to remove endpoint/dependency
+    
     custom_socket.remove_endpoint(endpoint_name='my_endpoint')
     custom_socket.remove_dependency(dependency_name='custom_script')
 
-    # or add new:
+    # or to add a new endpoint/dependency:
 
     custom_socket.add_endpoint(new_endpoint)  # see above code for endpoint examples;
     custom_socket.add_dependency(new_dependency)  # see above code for dependency examples;
 
+    # save changes on Syncano
+    
     custom_socket.update()
 
 
-Running the custom socket
+Running custom socket
 -------------------------
 
-To run custom socket use::
+To run a custom socket use::
 
-    # this will run the my_endpoint - and call the custom_script (method is GET);
+    # 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 custom socket
+Read all endpoints in a custom socket
 -----------------------------------
 
-To get the all defined endpoints in custom socket run::
+To get the all defined endpoints in a custom socket run::
 
     endpoints = custom_socket.get_endpoints()
 
@@ -122,7 +127,7 @@ To run a particular endpoint::
     # or:
     endpoint.run(method='POST', data={'name': 'test_name'})
 
-The data will be passed to the API call in the request body.
+Data will be passed to the API call in the request body.
 
 Read all endpoints
 ------------------
@@ -140,16 +145,16 @@ Above code will return a list with SocketEndpoint objects. To run such endpoint,
 Custom sockets endpoints
 ------------------------
 
-Each custom socket requires to define at least one endpoint. The endpoint is defined by name and
-a list of calls.  Each call is defined by a name and a list of methods. The name is a identification for dependency, eg.
+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 runtime matches) or a new one will be created.
-There's a special wildcard method: `methods=['*']` - this mean that any request with
+(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.
 
-To add an endpoint to the custom_socket use::
+To add an endpoint to a chosen custom_socket use::
 
-    my_endpoint = Endpoint(name='my_endpoint')  # again - no API call here
+    my_endpoint = Endpoint(name='my_endpoint')  # no API call here
     my_endpoint.add_call(ScriptCall(name='custom_script'), methods=['GET'])
     my_endpoint.add_call(ScriptCall(name='another_custom_script'), methods=['POST'])
 
@@ -158,9 +163,9 @@ To add an endpoint to the custom_socket use::
 Custom socket dependency
 ------------------------
 
-Each custom socket has dependency - this is a meta information for endpoint: which resource
-should be used to return the API call results. The dependencies are bind to the endpoints call objects.
-Currently the only supported dependency is script.
+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.
+Currently the only supported dependency is a Script.
 
 **Using new script**
 
@@ -201,15 +206,15 @@ Currently the only supported dependency is script.
 Custom socket recheck
 ---------------------
 
-The creation of the socket can fail - this happen, eg. when endpoint name is already taken by another
+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::
 
     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 (eg. mistake deletion), they will be created again.
-If the endpoints and dependencies do not met the criteria - the error will be returned in the status field.
+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.
 
 Custom socket - raw format
 --------------------------
@@ -236,4 +241,4 @@ If you prefer raw JSON format for creating sockets, you can resort to use it in
         ]
     )
 
-The disadvantage of this method is that - the JSON internal structure must be known by developer.
+The disadvantage of this method is that internal structure of the JSON file must be known by developer.
