Merge pull request #145 from supabase/fix/doc-tests

fix: doc test compilation errors

Author: burmecia

.github/workflows/test_supabase_wrappers.yml

@@ -0,0 +1,45 @@
+name: Test Wrappers
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Run supabase_wrappers tests
+    runs-on: ubuntu-20.04
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+
+    - run: |
+        sudo apt remove -y postgres*
+        sudo apt-get install -y wget gnupg
+        sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
+        wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
+        sudo apt-get update -y -qq --fix-missing
+        sudo apt-get install -y \
+          clang-10 \
+          llvm-10 \
+          clang \
+          gcc \
+          make \
+          build-essential \
+          libz-dev \
+          zlib1g-dev \
+          strace \
+          libssl-dev \
+          pkg-config \
+          postgresql-15 \
+          postgresql-server-dev-15
+        sudo chmod a+rwx `/usr/lib/postgresql/15/bin/pg_config --pkglibdir` `/usr/lib/postgresql/15/bin/pg_config --sharedir`/extension /var/run/postgresql/
+
+    - run: cargo install cargo-pgrx --version 0.9.8
+    - run: cargo pgrx init --pg15 /usr/lib/postgresql/15/bin/pg_config
+    - run: cd supabase-wrappers && cargo test

.github/workflows/test_wrappers.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   test:
-    name: Run tests
+    name: Run wrappers tests
     runs-on: ubuntu-20.04
 
     steps:

supabase-wrappers/src/interface.rs

@@ -628,18 +628,23 @@ pub trait ForeignDataWrapper {
     /// # Example
     ///
     /// ```rust,no_run
+    /// use pgrx::pg_sys::Oid;
+    /// use supabase_wrappers::prelude::check_options_contain;
+    ///
     /// fn validator(opt_list: Vec<Option<String>>, catalog: Option<Oid>) {
     ///     if let Some(oid) = catalog {
     ///         match oid {
     ///             FOREIGN_DATA_WRAPPER_RELATION_ID => {
     ///                 // check a required option when create foreign data wrapper
-    ///                 check_options_contain(&opt_list, "required_option");
+    ///                 check_options_contain(&opt_list, "foreign_data_wrapper_required_option");
     ///             }
     ///             FOREIGN_SERVER_RELATION_ID => {
     ///                 // check option here when create server
+    ///                 check_options_contain(&opt_list, "foreign_server_required_option");
     ///             }
     ///             FOREIGN_TABLE_RELATION_ID => {
     ///                 // check option here when create foreign table
+    ///                 check_options_contain(&opt_list, "foreign_table_required_option");
     ///             }
     ///             _ => {}
     ///         }

supabase-wrappers/src/lib.rs

@@ -60,8 +60,9 @@
 //! The FDW implements [`interface::ForeignDataWrapper`] trait must use [`wrappers_fdw`] macro and implement a `new()` initialization function. For example,
 //!
 //! ```rust,no_run
+//! # mod wrapper {
+//! use std::collections::HashMap;
 //! use supabase_wrappers::prelude::*;
-//!
 //! #[wrappers_fdw(
 //!    version = "0.1.0",
 //!    author = "Supabase",
@@ -76,7 +77,7 @@
 //! }
 //!
 //! impl ForeignDataWrapper for HelloWorldFdw {
-//!     pub fn new(options: &HashMap<String, String>) -> Self {
+//!     fn new(options: &HashMap<String, String>) -> Self {
 //!         // 'options' is the key-value pairs defined in `CREATE SERVER` SQL, for example,
 //!         //
 //!         // create server my_helloworld_server
@@ -95,7 +96,21 @@
 //!             tgt_cols: Vec::new(),
 //!         }
 //!     }
+//!
+//!     fn begin_scan(&mut self, quals: &[Qual], columns: &[Column], sorts: &[Sort], limit: &Option<Limit>, options: &HashMap<String, String>) {
+//!         // Do any initilization
+//!     }
+//!
+//!     fn iter_scan(&mut self, row: &mut Row) -> Option<()> {
+//!         // Return None when done
+//!         None
+//!     }
+//!
+//!     fn end_scan(&mut self) {
+//!         // Cleanup any resources
+//!     }
 //! }
+//! # }
 //! ```
 //!
 //! To develop a simple FDW supports basic query `SELECT`, you need to implement `begin_scan`, `iter_scan` and `end_scan`.
@@ -120,7 +135,24 @@
 //! Then we can implement [`interface::ForeignDataWrapper`] trait like below,
 //!
 //! ```rust,no_run
+//! use std::collections::HashMap;
+//! use supabase_wrappers::prelude::*;
+//!
+//! pub(crate) struct HelloWorldFdw {
+//!     // row counter
+//!     row_cnt: i64,
+//!
+//!     // target column name list
+//!     tgt_cols: Vec<Column>,
+//! }
 //! impl ForeignDataWrapper for HelloWorldFdw {
+//!     fn new(options: &HashMap<String, String>) -> Self {
+//!         Self {
+//!             row_cnt: 0,
+//!             tgt_cols: Vec::new(),
+//!         }
+//!     }
+//!
 //!     fn begin_scan(
 //!         &mut self,
 //!         _quals: &[Qual],
@@ -141,7 +173,7 @@
 //!         if self.row_cnt < 1 {
 //!             // add values to row if they are in target column list
 //!             for tgt_col in &self.tgt_cols {
-//!                 match tgt_col.as_str() {
+//!                 match tgt_col.name.as_str() {
 //!                     "id" => row.push("id", Some(Cell::I64(self.row_cnt))),
 //!                     "col" => row.push("col", Some(Cell::String("Hello world".to_string()))),
 //!                     _ => {}

supabase-wrappers/src/utils.rs

@@ -32,6 +32,7 @@ pub fn log_debug1(msg: &str) {
 /// For example,
 ///
 /// ```rust,no_run
+/// # use supabase_wrappers::prelude::report_info;
 /// report_info(&format!("this is an info"));
 /// ```
 #[inline]
@@ -51,6 +52,7 @@ pub fn report_info(msg: &str) {
 /// For example,
 ///
 /// ```rust,no_run
+/// # use supabase_wrappers::prelude::report_notice;
 /// report_notice(&format!("this is a notice"));
 /// ```
 #[inline]
@@ -70,6 +72,7 @@ pub fn report_notice(msg: &str) {
 /// For example,
 ///
 /// ```rust,no_run
+/// # use supabase_wrappers::prelude::report_warning;
 /// report_warning(&format!("this is a warning"));
 /// ```
 #[inline]
@@ -90,6 +93,7 @@ pub fn report_warning(msg: &str) {
 /// For example,
 ///
 /// ```rust,no_run
+/// # use supabase_wrappers::prelude::report_error;
 /// use pgrx::prelude::PgSqlErrorCode;
 ///
 /// report_error(
@@ -111,12 +115,20 @@ pub fn report_error(code: PgSqlErrorCode, msg: &str) {
 /// For example,
 ///
 /// ```rust,no_run
+/// # use supabase_wrappers::prelude::create_async_runtime;
+/// # struct Client {
+/// # }
+/// # impl Client {
+/// #     async fn query(&self, _sql: &str) -> Result<(), ()> { Ok(()) }
+/// # }
+/// # let client = Client {};
+/// # let sql = "";
 /// let rt = create_async_runtime();
 ///
-/// // client.query() is an async function
+/// // client.query() is an async function returning a Result
 /// match rt.block_on(client.query(&sql)) {
-///     Ok(result) => {...}
-///     Err(err) => {...}
+///     Ok(result) => { }
+///     Err(err) => { }
 /// }
 /// ```
 #[inline]
@@ -132,6 +144,9 @@ pub fn create_async_runtime() -> Runtime {
 /// For example,
 ///
 /// ```rust,no_run
+/// # use supabase_wrappers::prelude::require_option;
+/// # use std::collections::HashMap;
+/// # let options = &HashMap::new();
 /// require_option("my_option", options);
 /// ```
 pub fn require_option(opt_name: &str, options: &HashMap<String, String>) -> Option<String> {
@@ -151,7 +166,10 @@ pub fn require_option(opt_name: &str, options: &HashMap<String, String>) -> Opti
 /// For example,
 ///
 /// ```rust,no_run
-/// require_option_or("my_option", options, "default value");
+/// # use supabase_wrappers::prelude::require_option_or;
+/// # use std::collections::HashMap;
+/// # let options = &HashMap::new();
+/// require_option_or("my_option", options, "default value".to_string());
 /// ```
 pub fn require_option_or(
     opt_name: &str,