Adds testable examples to be automatically pulled in redis.io docs (#2601)

* Adding examples

* Update readme

* Update Readme

* Remove unneeded lines. Added an examples.json file

* Update readme for examples

* More fixes

* Add example tags

* Update examples.json

* Rename

* Add another hide block

* Temporary test

* Add example id for lpush and lrange

* Update readme

* Update output text

* Improve examples

* Move examples test dir to doctests

* Add redis v7's ExpireAtNX, ExpireAtXX, ExpireAtGT, ExpireAtLT, PExpireNX, PExpireXX, PExpireGT, PExpireLT, PExpireAtNX, PExpireAtXX, PExpireAtGT, PExpireAtLT

feat: Add redis v7's NX, XX, GT, LT expireat, pexpire, pexpireat variants

* add tests for new commands

add tests to coverage for the new commands

* Adds github workflow to add docexamples tests. Flushes db before every test.

* Fixes broken workflow file

* Adds Igor’s suggestion of keeping the instructions for docexamples in one place

* Removes unneeded “Missing” section, because it was solved as a workflow

* Revert "add tests for new commands"

This reverts commit af12cb6.

* Fixes review comments

* Specifies versions as strings instead of floats

---------

Co-authored-by: carner <[email protected]>

Author: elena-kolevska

.github/workflows/doctests.yaml

@@ -0,0 +1,41 @@
+name: Documentation Tests
+
+on:
+  push:
+    branches: [master, examples]
+  pull_request:
+    branches: [master, examples]
+
+permissions:
+  contents: read
+
+jobs:
+  doctests:
+    name: doctests
+    runs-on: ubuntu-latest
+
+    services:
+      redis-stack:
+        image: redis/redis-stack-server:latest
+        options: >-
+          --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
+        ports:
+          - 6379:6379
+
+    strategy:
+      fail-fast: false
+      matrix:
+        go-version: [ "1.18", "1.19", "1.20" ]
+
+    steps:
+      - name: Set up ${{ matrix.go-version }}
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Test doc examples
+        working-directory: ./doctests
+        run: go test

.gitignore

@@ -1,3 +1,4 @@
 *.rdb
 testdata/*
 .idea/
+.DS_Store

doctests/README.md

@@ -0,0 +1,22 @@
+# Command examples for redis.io
+
+These examples appear on the [Redis documentation](https://redis.io) site as part of the tabbed examples interface.
+
+## How to add examples
+
+- Create a Go test file with a meaningful name in the current folder. 
+- Create a single method prefixed with `Example` and write your test in it.
+- Determine the id for the example you're creating and add it as the first line of the file: `// EXAMPLE: set_and_get`.
+- We're using the [Testable Examples](https://go.dev/blog/examples) feature of Go to test the desired output has been written to stdout.
+
+### Special markup
+
+See https://github.com/redis-stack/redis-stack-website#readme for more details.
+
+## How to test the examples
+
+- Start a Redis server locally on port 6379
+- CD into the `doctests` directory
+- Run `go test` to test all examples in the directory.
+- Run `go test filename.go` to test a single file
+

doctests/lpush_lrange_test.go

@@ -0,0 +1,47 @@
+// EXAMPLE: lpush_and_lrange
+// HIDE_START
+package example_commands_test
+
+import (
+	"context"
+	"fmt"
+	"github.com/redis/go-redis/v9"
+)
+
+func ExampleLPushLRange() {
+	ctx := context.Background()
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr:     "localhost:6379",
+		Password: "", // no password docs
+		DB:       0,  // use default DB
+	})
+
+	// HIDE_END
+
+	// REMOVE_START
+	errFlush := rdb.FlushDB(ctx).Err() // Clear the database before each test
+	if errFlush != nil {
+		panic(errFlush)
+	}
+	// REMOVE_END
+
+	listSize, err := rdb.LPush(ctx, "my_bikes", "bike:1", "bike:2").Result()
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(listSize)
+
+	value, err := rdb.LRange(ctx, "my_bikes", 0, -1).Result()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(value)
+	// HIDE_START
+
+	// Output: 2
+	// [bike:2 bike:1]
+}
+
+// HIDE_END

doctests/set_get_test.go

@@ -0,0 +1,47 @@
+// EXAMPLE: set_and_get
+// HIDE_START
+package example_commands_test
+
+import (
+	"context"
+	"fmt"
+	"github.com/redis/go-redis/v9"
+)
+
+func ExampleSetGet() {
+	ctx := context.Background()
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr:     "localhost:6379",
+		Password: "", // no password docs
+		DB:       0,  // use default DB
+	})
+
+	// HIDE_END
+
+	// REMOVE_START
+	errFlush := rdb.FlushDB(ctx).Err() // Clear the database before each test
+	if errFlush != nil {
+		panic(errFlush)
+	}
+	// REMOVE_END
+
+	err := rdb.Set(ctx, "bike:1", "Process 134", 0).Err()
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("OK")
+
+	value, err := rdb.Get(ctx, "bike:1").Result()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("The name of the bike is %s", value)
+	// HIDE_START
+
+	// Output: OK
+	// The name of the bike is Process 134
+}
+
+// HIDE_END