update pgmq doc tooling

crates/pgmq/Cargo.toml

@@ -2,21 +2,22 @@
 name = "pgmq"
 version = "0.0.3"
 edition = "2021"
-
-description = "A Rust client for Postgres Message Queues"
-documentation = "https://github.com/CoreDB-io/coredb/crates/pgmq"
+authors = ["CoreDB.io"]
+description = "A message queue for Rust applications. The only external dependency is a Postgres database."
+documentation = "https://docs.rs/pgmq"
 homepage = "https://www.coredb.io"
 keywords = ["messaging", "queues", "postgres"]
 license = "MIT"
 readme = "README.md"
-repo = "https://github.com/CoreDB-io/coredb/crates/pgmq"
+repo = "https://github.com/CoreDB-io/coredb/tree/main/crates/pgmq"
 
 [dependencies]
 chrono = { version = "0.4.23", features = [ "serde" ] }
-serde = "1.0.152"
+serde = { version = "1.0.152" }
 serde_json = { version = "1.0.91", features = [ "raw_value" ] }
 sqlx = { version = "0.6", features = [ "runtime-tokio-native-tls" , "postgres", "chrono" ] }
 tokio = { version = "1", features = ["macros"] }
 
 [dev-dependencies]
+cargo-readme = "3.2.0"
 rand = "0.8.5"

crates/pgmq/Makefile

@@ -1,5 +1,11 @@
 POSTGRES_PASSWORD:=postgres
 
+update.readme:
+	cargo readme \
+		--no-title \
+		--no-indent-headings \
+		> README.md
+
 run.docker:
 	docker run --rm -d --name postgres -e POSTGRES_PASSWORD=${POSTGRES_PASSWORD} -p 5432:5432 postgres:15.1
 

crates/pgmq/README.md

@@ -1,85 +1,75 @@
 # Postgres Message Queue
 
+A lightweight messaging queue for Rust, using Postgres as the backend.
+Inspired by the [RSMQ project](https://github.com/smrchy/rsmq).
+
+# Examples
+
+First, start any Postgres instance. It is the only external dependency.
 
-### Start any Postgres instance
 ```bash
 docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres
 ```
-
-## Initialize a queue connection
+## Create a queue
 
 ```rust
 use pgmq::{Message, PGMQueue};
+let queue: PGMQueue = PGMQueue::new("postgres://postgres:postgres@0.0.0.0:5432".to_owned()).await.expect("Failed to connect to Postgres");
 
-
-let queue: PGMQueue = PGMQueue::new("postgres://postgres:postgres@0.0.0.0:5432".to_owned()).await;
-
-```
-
-## Create the queue
-
-```rust
 let myqueue = "myqueue".to_owned();
-queue.create(&myqueue).await?;
+queue.create(&myqueue).await.expect("Failed to create queue");
 ```
 
-## Sending messages to the queue
+## Sending messages
 
 `queue.enqueue()` can be passed any type that implements `serde::Serialize`. This means you can prepare your messages as JSON or as a struct.
 
-### JSON message
+#### as serde_json::Value
 ```rust
 let msg = serde_json::json!({
     "foo": "bar"
 });
-let msg_id = queue.enqueue(&myqueue, &msg).await;
+let msg_id = queue.enqueue(&myqueue, &msg).await.expect("Failed to enqueue message");
 ```
-
-### Struct messages
+#### as a struct
 ```rust
 use serde::{Serialize, Deserialize};
-
 #[derive(Serialize, Debug, Deserialize)]
 struct MyMessage {
     foo: String,
 }
 let msg = MyMessage {
     foo: "bar".to_owned(),
 };
-let msg_id: i64  = queue.enqueue(&myqueue, &msg).await;
+let msg_id: i64  = queue.enqueue(&myqueue, &msg).await.expect("Failed to enqueue message");
 ```
 
-## Reading messages from the queue
-
+## Reading messages
 Reading a message will make it invisible for the duration of the visibility timeout (vt).
-
 No messages are returned when the queue is empty or all messages are invisible.
-
-Messages can be parsed as JSON or as into a struct. `queue.read()` returns an `Option<Message<T>>` where `T` is the type of the message on the queue. It can be parsed as JSON or as a struct. 
-
-Note that when parsing into a `struct`, the application will panic if the message cannot be parsed as the type specified. For example, if the message expected is `MyMessage{foo: "bar"}` but` {"hello": "world"}` is received, the application will panic.
-
-### as JSON
+Messages can be parsed as JSON or as into a struct. `queue.read()` returns an `Option<Message<T>>`
+where `T` is the type of the message on the queue. It can be parsed as JSON or as a struct.
+Note that when parsing into a `struct`, the application will panic if the message cannot be
+parsed as the type specified. For example, if the message expected is
+`MyMessage{foo: "bar"}` but` {"hello": "world"}` is received, the application will panic.
+#### as serde_json::Value
 ```rust
 use serde_json::Value;
-
 let vt: u32 = 30;
 let read_msg: Message<Value> = queue.read::<Value>(&myqueue, Some(&vt)).await.expect("no messages in the queue!");
 ```
-
-### as a Struct
+#### as a Struct
 Reading a message will make it invisible for the duration of the visibility timeout (vt).
-
 No messages are returned when the queue is empty or all messages are invisible.
 ```rust
 use serde_json::Value;
-
 let vt: u32 = 30;
 let read_msg: Message<MyMessage> = queue.read::<MyMessage>(&myqueue, Some(&vt)).await.expect("no messages in the queue!");
 ```
-
 ## Delete a message
 Remove the message from the queue when you are done with it.
 ```rust
 let deleted = queue.delete(&read_msg.msg_id).await;
 ```
+
+License: MIT

crates/pgmq/src/lib.rs

@@ -1,3 +1,79 @@
+//! # Postgres Message Queue
+//!
+//! A lightweight messaging queue for Rust, using Postgres as the backend.
+//! Inspired by the [RSMQ project](https://github.com/smrchy/rsmq).
+//!
+//! # Examples
+//!
+//! First, start any Postgres instance. It is the only external dependency.
+//!
+//! ```bash
+//! docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres
+//! ```
+//! ## Create a queue
+//!
+//! ```rust
+//! use pgmq::{Message, PGMQueue};
+//! let queue: PGMQueue = PGMQueue::new("postgres://postgres:postgres@0.0.0.0:5432".to_owned()).await.expect("Failed to connect to Postgres");
+//!
+//! let myqueue = "myqueue".to_owned();
+//! queue.create(&myqueue).await.expect("Failed to create queue");
+//! ```
+//!
+//! ## Sending messages
+//!
+//! `queue.enqueue()` can be passed any type that implements `serde::Serialize`. This means you can prepare your messages as JSON or as a struct.
+//!
+//! #### as serde_json::Value
+//! ```rust
+//! let msg = serde_json::json!({
+//!     "foo": "bar"
+//! });
+//! let msg_id = queue.enqueue(&myqueue, &msg).await.expect("Failed to enqueue message");
+//! ```
+//! #### as a struct
+//! ```rust
+//! use serde::{Serialize, Deserialize};
+//! #[derive(Serialize, Debug, Deserialize)]
+//! struct MyMessage {
+//!     foo: String,
+//! }
+//! let msg = MyMessage {
+//!     foo: "bar".to_owned(),
+//! };
+//! let msg_id: i64  = queue.enqueue(&myqueue, &msg).await.expect("Failed to enqueue message");
+//! ```
+//!
+//! ## Reading messages
+//! Reading a message will make it invisible for the duration of the visibility timeout (vt).
+//! No messages are returned when the queue is empty or all messages are invisible.
+//! Messages can be parsed as JSON or as into a struct. `queue.read()` returns an `Option<Message<T>>`
+//! where `T` is the type of the message on the queue. It can be parsed as JSON or as a struct.
+//! Note that when parsing into a `struct`, the application will panic if the message cannot be
+//! parsed as the type specified. For example, if the message expected is
+//! `MyMessage{foo: "bar"}` but` {"hello": "world"}` is received, the application will panic.
+//! #### as serde_json::Value
+//! ```rust
+//! use serde_json::Value;
+//! let vt: u32 = 30;
+//! let read_msg: Message<Value> = queue.read::<Value>(&myqueue, Some(&vt)).await.expect("no messages in the queue!");
+//! ```
+//! #### as a Struct
+//! Reading a message will make it invisible for the duration of the visibility timeout (vt).
+//! No messages are returned when the queue is empty or all messages are invisible.
+//! ```rust
+//! use serde_json::Value;
+//! let vt: u32 = 30;
+//! let read_msg: Message<MyMessage> = queue.read::<MyMessage>(&myqueue, Some(&vt)).await.expect("no messages in the queue!");
+//! ```
+//! ## Delete a message
+//! Remove the message from the queue when you are done with it.
+//! ```rust
+//! let deleted = queue.delete(&read_msg.msg_id).await;
+//! ```
+
+#![doc(html_root_url = "https://docs.rs/pgmq/")]
+
 use serde::{Deserialize, Serialize};
 use sqlx::error::Error;
 use sqlx::postgres::{PgPoolOptions, PgRow};