doc: add getting started section

Author: jason810496

doc/getting-started.rst

@@ -42,6 +42,84 @@ Or using **Docker Compose** to start Postgres with ``PGMQ`` extension:
 
 For more information, see `PGMQ GitHub <https://github.com/tembo-io/pgmq>`_.
 
-PGMQ SQLAlchemy
----------------
+pgmq-sqlalchemy Setup
+---------------------
 
+.. tip::
+
+    See `API Reference <api-reference>`_ for **more examples and detailed usage**.
+
+For ``dispatcher.py``:
+
+    .. code-block:: python
+
+        from typing import List
+        from pgmq_sqlalchemy import PGMQueue
+
+        postgres_dsn = 'postgresql://postgres:postgres@localhost:5432/postgres'
+
+        pgmq = PGMQueue(dsn=postgres_dsn)
+        pgmq.create_queue('my_queue')
+
+        msg = {'key': 'value', 'key2': 'value2'}
+        msg_id:int = pgmq.send('my_queue', msg)
+
+        # could also send a list of messages
+        msg_ids:List[int] = pgmq.send_batch('my_queue', [msg, msg])
+
+    .. seealso::
+
+        .. _init_method: ref:`pgmq_sqlalchemy.PGMQueue.__init__`
+        .. |init_method| replace:: :py:meth:`~pgmq_sqlalchemy.PGMQueue.__init__`
+
+        .. _send_method: ref:`pgmq_sqlalchemy.PGMQueue.send`
+        .. |send_method| replace:: :py:meth:`~pgmq_sqlalchemy.PGMQueue.send`
+
+        See |init_method|_ for more options on how to initialize the ``PGMQueue`` object, and advance usage with |send_method|_ on `API Reference <api-reference>`_.
+
+
+For ``consumer.py``:
+
+    .. code-block:: python
+
+        from pgmq_sqlalchemy import PGMQueue
+        from pgmq_sqlalchemy.schema import Message
+
+        postgres_dsn = 'postgresql://postgres:postgres@localhost:5432/postgres'
+
+        pgmq = PGMQueue(dsn=postgres_dsn)
+
+        # read a single message
+        msg:Message = pgmq.read('my_queue')
+
+        # read a batch of messages
+        msgs:List[Message] = pgmq.read_batch('my_queue', 10)
+
+    .. seealso::
+
+        .. _read_with_poll_method: ref:`pgmq_sqlalchemy.PGMQueue.read_with_poll`
+        .. |read_with_poll_method| replace:: :py:meth:`~pgmq_sqlalchemy.PGMQueue.read_with_poll`
+
+        .. _read_method: ref:`pgmq_sqlalchemy.PGMQueue.read`
+        .. |read_method| replace:: :py:meth:`~pgmq_sqlalchemy.PGMQueue.read`
+
+        See |read_with_poll_method|_ for reading messages with long-polling, and advance usage with |read_method|_ for **consumer retries mechanism** and more control over message consumption on `API Reference <api-reference>`_.
+
+For ``monitor.py``:
+
+    .. code-block:: python
+
+        from pgmq_sqlalchemy import PGMQueue
+        from pgmq_sqlalchemy.schema import QueueMetrics
+
+        postgres_dsn = 'postgresql://postgres:postgres@localhost:5432/postgres'
+
+        pgmq = PGMQueue(dsn=postgres_dsn)
+
+        # get queue metrics
+        metrics:QueueMetrics = pgmq.metrics('my_queue')
+        print(metrics.queue_length)
+        print(metrics.total_messages)
+
+
+        

pgmq_sqlalchemy/queue.py

@@ -522,6 +522,9 @@ def read(self, queue_name: str, vt: Optional[int] = None) -> Optional[Message]:
         .. _for_update_skip_locked: https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE
         .. |for_update_skip_locked| replace:: **FOR UPDATE SKIP LOCKED**
 
+        .. _read_method: ref:`pgmq_sqlalchemy.PGMQueue.read`
+        .. |read_method| replace:: :py:meth:`~pgmq_sqlalchemy.PGMQueue.read`
+
         Read a message from the queue.
 
         Returns:
@@ -749,6 +752,11 @@ def read_with_poll(
         poll_interval_ms: int = 100,
     ) -> Optional[List[Message]]:
         """
+
+        .. _read_with_poll_method: ref:`pgmq_sqlalchemy.PGMQueue.read_with_poll`
+        .. |read_with_poll_method| replace:: :py:meth:`~pgmq_sqlalchemy.PGMQueue.read_with_poll`
+
+
         | Read messages from a queue with long-polling.
         |
         | When the queue is empty, the function block at most ``max_poll_seconds`` seconds.