ouch_doc: added ouch user guide

docs/user_guide_itch.rst

@@ -48,6 +48,7 @@ Use the example below to implement a program that will tail itch messages from t
 
 
     stopped = asyncio.Event()
+    port = 1234  # give the proper itch server port
 
 
     async def itch_output(itch_message):
@@ -71,7 +72,6 @@ Use the example below to implement a program that will tail itch messages from t
 
     async def main():
         # Step1: connect
-        port = 1234  # give the proper itch server port
         itch_session = await itch_feed.connect_async(
             ('hostname', port),
             'itch username',  # itch username, max 6 characters
@@ -82,10 +82,7 @@ Use the example below to implement a program that will tail itch messages from t
             sequence=1  # 0 to listen from HEAD, 1 to listen from start, n to listen from n
         )
 
-        # Wait forever until the server closes the connection
-        await asyncio.sleep(5)
-
-        print("Closing the itch session...")
+        print("wait for server to close the session")
         await stopped.wait()
 
 
@@ -94,7 +91,7 @@ Use the example below to implement a program that will tail itch messages from t
 
 *A simple itch tail program*
 
-Slightly modified version where we do not use dispatchers instead explicitely call `receive_message()` method.
+Slightly modified version where we do not use dispatchers instead explicitly call `receive_message()` method.
 
 .. code-block:: python
 
@@ -103,9 +100,11 @@ Slightly modified version where we do not use dispatchers instead explicitely ca
     from nasdaq_protocols_messages import itch_feed
 
 
+    port = 1234  # give the proper itch server port
+
+
     async def main():
         # Step1: connect
-        port = 1234  # give the proper itch server port
         itch_session = await itch_feed.connect_async(
             ('hostname', port),
             'itch username',  # itch username, max 6 characters

docs/user_guide_ouch.rst

@@ -5,3 +5,117 @@ OUCH User Guide
 
 The `nasdaq_protocols.ouch` module provides an API to interact with OUCH servers.
 Refer :ref:`api-reference-ouch`. for more information on the API.
+
+This package **only** provides the core implementation of the OUCH protocols, like message serialization
+deserialization, session handling, etc. It **does not** define any actual OUCH messages. The actual OUCH
+messages has to be defined by the user of this package. The first step is to create a new python package
+which contains the messages definitions for all the protocols that the user wants to use.
+
+This package provides a command line utility `nasdaq-protocols-create-new-project` to create a new python package
+and all the necessary files.
+
+Follow the steps in :ref:`user-guide-create-new-project` to create a new python package for application specific
+messages.
+
+
+.. note::
+
+    This rest of the guide assumes that you have built a new python project using the steps mentioned in
+    :ref:`user-guide-create-new-project`.
+
+
+The generated project will contain a file `ouch_<app_name>.py` which will contain the following
+    - OUCH message definitions
+    - OUCH Client Session for this application
+
+Using the generated code, you can connect to a OUCH server and start sending/receiving messages.
+
+
+The `nasdaq_protocols.ouch` module provides an API to interact with OUCH servers.
+Refer :ref:`api-reference-ouch`. for more information on the API.
+
+
+Sending Message to a OUCH Server
+--------------------------------
+
+Sample Message Definition
+^^^^^^^^^^^^^^^^^^^^^^^^^
+For our test ouch app, lets define our OUCH messages in the file `<app_name>.xml` as follows,
+
+.. code-block:: XML
+
+    <root>
+        <messages-root>
+            <message id="EnterOrder" message-id="65" direction="incoming">
+                <fields>
+                    <field name="orderBookId" type="int_4_be"/>
+                    <field name="side" type="char_iso-8859-1"/>
+                    <field name="quantity" type="int_8_be"/>
+                    <field name="price" type="int_8_be"/>
+                </fields>
+            </message>
+            <message id="Accepted" message-id="75" direction="outgoing">
+                <fields>
+                    <field name="orderId" type="int_8_be"/>
+                </fields>
+            </message>
+            <message id="Rejected" message-id="85" direction="outgoing">
+                <fields>
+                    <field name="reason" type="int_2_be"/>
+                </fields>
+            </message>
+        </messages-root>
+    </root>
+
+
+Sending and Receiving OUCH messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With the above message definition, we can now send the ouch message as follows.
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+    import asyncio
+    # from the generated package we import the application we want to use
+    from nasdaq_protocols_messages import ouch_oe
+
+
+    port = 1234  # give the proper ouch server port
+
+
+    async def main():
+        # Step1: connect
+        ouch_session = await ouch_oe.connect_async(
+            ('hostname', port),
+            'ouch username',  # ouch username, max 6 characters
+            'pwdchange', # ouch password, max 10 characters
+            '', # session id
+            sequence=0  # 0 to listen from HEAD, 1 to listen from start, n to listen from n
+        )
+
+        # Step2: Prepare a message
+        enter_order = ouch_oe.EnterOrder()  # This is the message we defined in the xml file
+        enter_order.orderBookId = 1
+        enter_order.side = 'B'
+        enter_order.quantity = 100
+        enter_order.price = 20
+
+        # Step3: Send the message to the server.
+        ouch_session.send_message(enter_order)
+
+        # Step4: receive the first message from the server.
+        output = await ouch_session.receive_message()
+        if isinstance(output, ouch_oe.Accepted):
+            print("Order accepted")
+        elif isinstance(output, ouch_oe.Rejected):
+            print("Order rejected")
+
+        # Step5: Close the session
+        print("Closing the ouch session...")
+        await ouch_session.close()
+
+
+    if __name__ == '__main__':
+        asyncio.run(main())
+
+*A simple ouch send and receive program*

src/nasdaq_protocols/tools/templates/toml.mustache

@@ -21,7 +21,7 @@ version = "0.0.1"
 # DEPENDENCIES
 # add your dependencies to the below list
 dependencies = [
-    'nasdaq-protocols>=0.0.1',
+    'nasdaq-protocols',
 ]
 
 # VERSION