Documentation for itch and ouch

docs/api_reference.rst

@@ -5,5 +5,7 @@ API Reference
    :maxdepth: 1
    :caption: Contents:
 
-   common_api_reference
-   soup_api_reference
+   api_reference_soup
+   api_reference_itch
+   api_reference_ouch
+   api_reference_common

docs/api_reference_itch.rst

@@ -0,0 +1,22 @@
+.. _api-reference-itch:
+ITCH API Reference
+==================
+
+Itch
+----
+.. automodule:: nasdaq_protocols.itch
+
+
+Itch Session
+^^^^^^^^^^^^
+.. autoclass:: nasdaq_protocols.itch.session.ItchSessionId
+    :show-inheritance: True
+
+.. autoclass:: nasdaq_protocols.itch.session.ClientSession
+    :show-inheritance: True
+    :undoc-members: ['send_heartbeat']
+
+
+Itch Messages
+^^^^^^^^^^^^^
+.. automodule:: nasdaq_protocols.itch.core

docs/api_reference_ouch.rst

@@ -0,0 +1,22 @@
+.. _api-reference-ouch:
+OUCH API Reference
+==================
+
+Ouch
+----
+.. automodule:: nasdaq_protocols.ouch
+
+
+Ouch Session
+^^^^^^^^^^^^
+.. autoclass:: nasdaq_protocols.ouch.session.OuchSessionId
+    :show-inheritance: True
+
+.. autoclass:: nasdaq_protocols.ouch.session.ClientSession
+    :show-inheritance: True
+    :undoc-members: ['send_heartbeat']
+
+
+Ouch Messages
+^^^^^^^^^^^^^
+.. automodule:: nasdaq_protocols.ouch.core

docs/soup_api_reference.rst → docs/api_reference_soup.rst

@@ -1,4 +1,5 @@
-SOUP api reference
+.. _api-reference-soup:
+SOUP API Reference
 ==================
 
 Soup

docs/index.rst

@@ -8,13 +8,25 @@ Welcome to nasdaq-protocols's documentation!
 
 .. automodule:: nasdaq_protocols
 
+nasdaq-protocols contains client side implementations of the various
+publicly available protocols used by Nasdaq ecosystem.
+
+This package contains only the core implementations of the protocols like message
+serialization, deserialization, message validation and session handling. It does not
+contain any actual messages that are exchanged between the client and the server.
+
+The actual messages are application specific and hence has to be defined by the
+user of this library. The user has to define the messages as per the protocol specification
+by extending the base message class defined in the package.
+
+Refer to the :ref:`user-guide`. for more information on how to define the messages and use this package.
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
-   install
-   api_reference
    user_guide
+   api_reference
    developer_guide
    LICENSE
 

docs/install.rst

@@ -5,4 +5,4 @@ To use nasdaq-protocols, install it using pip:
 
 .. code-block:: console
 
-   (.venv) $ pip install nasdaq-protocols
+   $ pip install nasdaq-protocols

docs/user_guide.rst

@@ -1,35 +1,13 @@
+.. _user-guide:
+
 User Guide
 ==========
 
-SOUP
-____
-
-Connect to Soup session
------------------------
-Example of connecting to a Soup session and receiving messages.
-
-.. code-block:: python
-
-    import asyncio
-    from nasdaq_protocols import Soup
-
-    stopped = asyncio.Event()
-
-    async def on_msg(msg):
-        print(msg)
-
-    async def on_close():
-        stopped.set()
-        print('closed')
-
-    async def main():
-        session = await soup.connect_async(
-            ('host', port), 'user', 'password',
-            sequence=1, on_msg_coro=on_msg, on_close_coro=on_close
-        )
-        await stopped.wait()
-
-    if __name__ == '__main__':
-        asyncio.run(main())
+.. toctree::
+   :maxdepth: 1
+   :caption: User Guides:
 
-*A simple soup tail program*
+   install
+   user_guide_soup
+   user_guide_ouch
+   user_guide_itch

docs/user_guide_itch.rst

@@ -0,0 +1,5 @@
+ITCH User Guide
+===============
+
+The `nasdaq_protocols.itch` module provides an API to interact with ITCH servers.
+Refer :ref:`api-reference-itch`. for more information on the API.

docs/user_guide_ouch.rst

@@ -0,0 +1,5 @@
+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.

docs/user_guide_soup.rst

@@ -0,0 +1,89 @@
+SOUP User Guide
+===============
+
+SoupBinTCP 4.00 is a lightweight point-to-point protocol, built on top of TCP/IP
+sockets that allow delivery of a set of sequenced and unsequenced messages from a
+server to a client in real-time. SoupBinTCP guarantees that the client receives each
+sequenced message generated by the server in the correct order, even across
+underlying TCP/IP socket connection failures.
+
+Refer to the `Official SOUP Documentation <https://www.nasdaq.com/docs/SoupBinTCP%204.0.pdf>`_ for more information
+on how SOUP protocol works.
+
+The `nasdaq_protocols.soup` module provides an API to interact with SOUP servers and clients.
+Refer :ref:`api-reference-soup`. for more information on the API.
+
+
+Connect to Soup Server
+----------------------
+Example of connecting to a Soup server and receiving messages.
+
+.. code-block:: python
+
+    #!/usr/bin/env python3
+    import asyncio
+    from nasdaq_protocols import soup
+
+
+    stopped = asyncio.Event()
+
+
+    async def on_msg(msg):
+        print(msg)
+
+
+    async def on_close():
+        stopped.set()
+        print('closed')
+
+
+    async def main():
+        port = 1234  # Give the actual port number
+        session = await soup.connect_async(
+            ('hostname or ip', port),
+            'username', # Soup username, max 6 characters (as per spec)
+            'password', # Soup password, max 10 characters (as per spec)
+            sequence=1, # 0 to listen from HEAD, 1 to listen from start, n to listen from n
+            on_msg_coro=on_msg, # callback for receiving messages
+            on_close_coro=on_close # callback for indicating server closed the connection
+        )
+
+        # To send a message to the server
+        # session.send_unseq_data(b'some bytes')
+
+        await stopped.wait()
+
+
+    if __name__ == '__main__':
+        asyncio.run(main())
+
+*A simple soup tail program*
+
+
+A slightly modified version of the same example but not using dispatchers for `on_msg` and `on_close` callbacks.
+
+
+.. code-block:: python
+
+    #!/usr/bin/env python3
+    import asyncio
+    from nasdaq_protocols import soup
+
+
+    async def main():
+        port = 1234  # Give the actual port number
+        session = await soup.connect_async(
+            ('hostname or ip', port), 'username', 'password',
+            sequence=1
+        )
+        print(await session.receive_msg())
+        await session.close()
+
+        # To send a message to the server
+        # session.send_unseq_data(b'some bytes')
+
+
+    if __name__ == '__main__':
+        asyncio.run(main())
+
+*A simple soup tail program without dispatchers*

src/nasdaq_protocols/__init__.py

@@ -1,4 +0,0 @@
-"""
-nasdaq-protocols contains client side implementations of the various
-publicly available protocols used by Nasdaq ecosystem.
-"""