Adds a clients overview page (#166)

### Description

Adds a client page to docs on the website. The page is added to the top
nav docs, called "Client Libraries", and its url is top level
`valkey.io/clients `.
This PR is dependent on the [complimentary docs
PR](valkey-io/valkey-doc#164) being merged.

#### How it works - 
- The `init-topics.sh` script was modified to expect the path to the
clients docs folder as its second argument. It creates a symlink to it,
called `build-clients`. The clients folder in docs holds json files
specifying each client's details and features.
- `content/clients/_index.md` has in its frontmatter the list of paths
to the clients appearing in this page. This list is used by the
`client-list.html` template to render the specified clients' data. This
template also includes the `client-feature-table.html` template that
renders the same json files to produce a table comparing which features
each client implements.

### Issues Resolved
[#161](valkey-io/valkey-doc#161)
Dependent on this PR being merged -
[#164](valkey-io/valkey-doc#164)

### Check List
- [x] Commits are signed per the DCO using `--signoff`

By submitting this pull request, I confirm that my contribution is made
under the terms of the BSD-3-Clause License.

---------

Signed-off-by: lior sventitzky <[email protected]>
Signed-off-by: Lior Sventitzky <[email protected]>
Co-authored-by: Madelyn Olson <[email protected]>

Author: liorsve

.github/workflows/zola-deploy.yml

@@ -34,10 +34,10 @@ jobs:
           repository: valkey-io/valkey
           path: valkey
 
-      - name: Init commands and topics
+      - name: Init commands, topics and clients
         run: |
           cd website
-          ./build/init-topics.sh ../valkey-doc/topics 
+          ./build/init-topics-and-clients.sh ../valkey-doc/topics ../valkey-doc/clients
           ./build/init-commands.sh ../valkey-doc/commands ../valkey/src/commands
       - name: Build only
         uses: shalzz/[email protected]

.gitignore

@@ -3,6 +3,7 @@ public
 build-command-docs
 build-command-json
 build-topics
+build-clients
 content/commands/*
 !content/commands/_index.md
 content/topics/*

README.md

@@ -28,16 +28,17 @@ Changes to external content (command reference, documentation topics) require a
 
 ## Building additional content
 
-**By default, the site will build without documentation topics nor command reference.**
-This content is stored within the `valkey-io/valkey-doc` and `valkey-io/valkey` repos respectively.
+**By default, the site will build without documentation topics, command reference, or the clients page.**
+The content for documentation topics and the clients page are stored within the `valkey-io/valkey-doc` repo. 
+The content for the command reference page is in the `valkey-io/valkey` repo.
 
 If you want to build the site with this content, you'll need to have a local copy of `valkey-io/valkey-doc` and `valkey-io/valkey` _outside_ of this repo.
-Then follow the instructions to [build the documentation topics](#building-the-documentation-topics) and/or [build the command reference](#building-the-command-reference).
+Then follow the instructions to [build the documentation topics and clients](#building-the-documentation-topics-and-clients-page) and/or [build the command reference](#building-the-command-reference).
 The instructions show how to use scripts that create symbolic links to the `valkey-io/valkey-doc` and `valkey-io/valkey` repos as well as create a series of empty stub files that tell Zola to create pages.
 
-### Building the documentation topics
+### Building the documentation topics and clients page
 
-Documentation 'topics' (i.e. `/topics/keyspace/`, `/topics/encryption/`, `/topics/transactions/`) sources content from `valkey-io/valkey-doc`.
+Documentation 'topics' (i.e. `/topics/keyspace/`, `/topics/encryption/`, `/topics/transactions/`) and the client libraries' data (i.e. `/client-page-clients/nodejs/valkey-glide`, `/client-page-clients/python/valkey-py`) sources content from `valkey-io/valkey-doc`.
 
 ```mermaid
 flowchart TD
@@ -51,12 +52,12 @@ First, stop the `zola serve` process if you're running it.
 From the root directory of this repo run:
 
 ```shell
-# You should only need to run this once or when you add a new topic.
-./build/init-topics.sh ../valkey-doc/topics 
+# You should only need to run this once or when you add a new topic/client.
+./build/init-topics-and-clients.sh ../valkey-doc/topics ../valkey-doc/clients
 ```
 
 Then, restart Zola.
-Point your browser at `http://127.0.0.1:1111/topics/` and you should see the fully populated list of topics.
+Point your browser at `http://127.0.0.1:1111/topics/` and you should see the fully populated list of topics and clients.
 All files created in this process are ignored by git.
 Commit your changes to your local copy of `valkey-io/valkey-doc`.
 

build/init-topics.sh renamed to build/init-topics-and-clients.sh

@@ -8,12 +8,22 @@ if [ -z "$1" ]; then
     exit 1
 fi 
 
+if [ -z "$2" ]; then
+    echo "You must supply a path to the clients directory as the first argument" 
+    exit 1
+fi 
+
 # check for validity of these agruments as paths
 if [ ! -d "$1" ]; then
     echo "The topics directory must exist and be a valid path"
     exit 1
 fi
 
+if [ ! -d "$2" ]; then
+    echo "The clients directory must exist and be a valid path"
+    exit 1
+fi
+
 # check for old style /docs/topics
 if [ -e "content/docs/topics" ]; then
     echo "Documentation topic files have moved. Delete content/docs/topics before proceeding."
@@ -55,3 +65,11 @@ do
     cp ${fname} ./content/topics/${base}
 done
 echo "Copied images to topics directory."
+
+
+#create symlink to clients, expect if it already exists
+if [ ! -L build-clients -o "$(readlink build-clients)" != "$2" ]; then
+    ln -s $2 ./build-clients
+fi
+echo "Symlink to clients has been created at ./build-clients "
+

config.toml

@@ -21,6 +21,7 @@ highlight_code = true
 [extra]
 command_description_path = "../build-command-docs/"
 command_json_path = "../build-command-json/"
+client_json_path = "../build-clients/"
 doc_topic_path = "../build-topics/"
 
 review_list = [
@@ -46,4 +47,4 @@ publish_hold = [
     "/topics/internals-vm/",
     "/topics/internals/",
     "/topics/rdd/"
-]
+]

content/clients/_index.md

@@ -0,0 +1,59 @@
++++
+title = "Client Libraries"
+template = "client-list.html"
+[extra]
+recommended_clients_paths = [
+    "/python/valkey-GLIDE.json",
+    "/python/valkey-py.json",
+    "/node.js/valkey-GLIDE.json",
+    "/node.js/iovalkey.json",
+    "/java/valkey-GLIDE.json",
+    "/java/valkey-java.json",
+    "/go/valkey-GLIDE.json",
+    "/go/valkey-go.json",
+    "/php/phpredis.json",
+    "/php/predis.json",
+    ] 
+
+client_fields =[
+    "name",
+    "language",
+    "read_from_replica",
+    "smart_backoff_to_prevent_connection_storm",
+    "pubsub_state_restoration",
+    "cluster_scan",
+    "latency_based_read_from_replica",
+    "AZ_based_read_from_replica",
+    "client_side_caching",
+    "client_capa_redirect",
+    "persistent_connection_pool"
+    ]
+
++++
+
+This page offers an overview of recommended Valkey clients for various programming languages. A table of advanced features supported by the respective clients is provided, highlighting the unique advantages of one client over another.
+
+This page includes only clients which are regularly tested and recommended. However, it's important to note that other clients that support Redis OSS version 7.2 are compatible with Valkey 7.2 and above. To add your client to the list, please refer to [this link.](https://github.com/valkey-io/valkey-doc/blob/main/clients/README.md)
+
+<!-- split -->
+
+Advanced Features Overview
+-----
+
+1. **Read from Replica** - The ability to read data from a replica node, which can be useful for load balancing and reducing the load on the primary node. This feature is particularly important in read-heavy applications.
+
+2. **Smart Backoff to Prevent Connection Storm** - A strategy used to prevent connection storms by progressively updating the wait time between retries when attempting to reconnect to a Valkey server. This helps to reduce the load on the server during topology updates, periods of high demand or network instability.
+
+3. **PubSub State Restoration** - The ability to restore the state of Pub/Sub (publish/subscribe) channels after a client reconnects. This feature ensures that clients can continue receiving messages after disconnections or topology updates such as adding or removing shards, for both legacy Pub/Sub and sharded Pub/Sub. The client will automatically resubscribe the connections to the new node. The advantage is that the application code is simplified, and doesn’t have to take care of resubscribing to new nodes during reconnects.
+
+4. **Cluster Scan** - This feature ensures that the user experience and guarantees for scanning a cluster are identical to those for scanning a single node. The SCAN function operates as a cursor-based iterator. With each command, the server provides an updated cursor, which must be used as the cursor argument in subsequent calls. A complete iteration with SCAN retrieves all elements present in the collection from start to finish. If an element exists in the collection at the beginning and remains until the end of the iteration, SCAN will return it. Conversely, any element removed before the iteration begins and not re-added during the process will not be returned by SCAN. A client supporting this feature ensures the scan iterator remains valid even during failovers or cluster scaling (in or out) during the SCAN operation. 
+
+5. **Latency-Based Read from Replica** - This feature enables reading data from the nearest replica, i.e., the replica that offers the best latency. It supports complex deployments where replicas are distributed across various distances, including different geographical regions, to ensure data is read from the closest replica, thereby minimizing latency.
+
+6. **AZ-Based Read from Replica** - This feature enables reading data from replicas within the same Availability Zone (AZ). When running Valkey in a cloud environment across multiple AZs, it is preferable to keep traffic localized within an AZ to reduce costs and latency. By reading from replicas in the same AZ as the client, you can optimize performance and minimize cross-AZ data transfer charges. For more detailed information about this feature and its implementation, please refer to [this link.](https://github.com/valkey-io/valkey/pull/700)
+
+7. **Client Side Caching** - Valkey client-side caching is a feature that allows clients to cache the results of Valkey queries on the client-side, reducing the need for frequent communication with the Valkey server. This can significantly improve application performance by lowering latency, reducing the network usage and cost and reducing the load on the Valkey server. 
+
+8. **`CLIENT CAPA redirect` Support** - The `CLIENT CAPA redirect` feature was introduced in Valkey 8 to facilitate seamless upgrades without causing errors in standalone mode. When enabled, this feature allows the replica to redirect data access commands (both read and write operations) to the primary instance. This ensures uninterrupted service during the upgrade process. For more detailed information about this feature, please refer to [this link.](https://github.com/valkey-io/valkey/pull/325)
+
+9. **Persistent Connection Pool** - This feature enables the Valkey client to maintain a pool of persistent connections to the Valkey server, improving performance and reducing overhead. Instead of establishing a new connection for each request, the client can reuse existing connections from the pool, minimizing the time and resources required for connection setup.

content/docs/index.md

@@ -9,3 +9,5 @@ body_class=  "blocks-page"
 
 * [Command Reference](/commands/) A categorized listing of all Valkey commands
 * [Documentation by topic](/topics/) In-depth documentation covering a wide variety of operational and usage subjects
+* [Client Libraries](/clients/) An overview of recommended Valkey clients and their features.
+

sass/_valkey.scss

@@ -697,3 +697,145 @@ pre table {
 
   border-top: 1px solid $grey-dk-100;
 }
+
+.client-list {
+  h2 {
+    margin-top: 2rem;
+    margin-bottom: 1rem;
+
+  }
+
+
+  .language-clients {
+    margin-bottom: 3rem;
+
+    .client-item {
+      margin-bottom: 2rem;
+      padding: 1rem;
+      border: 1px solid #e0e0e0;
+      border-radius: 4px;
+      background-color: #fff;
+      max-width: 1500px; 
+      width: 100%;
+
+      h3 {
+        margin-top: 0;
+        color: #222;
+      }
+
+      ul {
+        list-style-type: none;
+        padding-left: 0;
+    
+        > li {
+          position: relative;
+          padding-left: 1.5em;
+    
+          &::before {
+            content: "\2022";  
+            position: absolute;
+            left: 0.5em;
+            color: #000; 
+          }
+    
+          > ul > li {
+            padding-left: 1.5em;
+    
+            &::before {
+              content: "\25E6";  
+              position: absolute;
+              left: 0.5em;
+              color: #000;  
+            }
+          }
+        }
+      }
+
+      code, pre {
+        background-color: #f5f5f5;
+        padding: 0.2rem 0.4rem;
+        border-radius: 3px;
+        width:850px
+      }
+    }
+  }
+}
+
+.feature-comparison-table {
+  margin-top: 3rem;
+
+  .table-container {
+    padding: 0;
+    background-color: #fafafa;
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    overflow-x: auto;
+
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      th, td {
+        padding: 8px 12px;
+        text-align: center;
+        border-right: 1px solid #e0e0e0;
+        border-bottom: 1px solid #e0e0e0;
+      }
+
+      th:first-child,
+      td:first-child {
+        position: sticky;
+        left: 0;
+        background-color: #fafafa; 
+        z-index: 2;
+      }
+    }
+
+    .table-header {
+      background-color: #f4f4f4; 
+      font-weight: bold;
+
+      .table-header-cell {
+        padding: 10px;
+        color: #555;
+        position: sticky;
+        top: 0;
+        z-index: 1;
+        background-color: #f4f4f4;
+      }
+
+      .table-header-cell:first-child {
+        z-index: 3; 
+      }
+    }
+
+    .table-row {
+      &.even-row {
+        background-color: #f9f9f9;
+      }
+      &.odd-row {
+        background-color: #fff;
+      }
+
+      .table-cell {
+        color: #444; 
+        white-space: normal;
+        word-wrap: break-word;
+
+        &:first-child {
+          font-weight: bold;
+          color: #555;
+        }
+      }
+    }
+  }
+}
+
+.checkmark-true {
+  color: green;
+  font-weight: bold;
+}
+
+.checkmark-false {
+  color: rgb(190, 9, 9);
+  font-weight: bold;
+}

templates/client-feature-table.html

@@ -0,0 +1,34 @@
+{% import "macros/docs.html" as docs %}
+
+{% block main_content %}
+    <hr/>
+    <h2 >Feature Comparison Table</h2>
+
+    <div class="table-container">
+        <table >
+            <thead>
+                <tr class="table-header">
+                    {% for header in client_fields %}
+                        <th class="table-header-cell">{{ header | replace(from="_", to=" ") |  title | replace (from= "Az", to= "AZ") }}</th>
+                    {% endfor %}
+                </tr>
+            </thead>
+            <tbody>
+                {%- for path in client_paths %}
+                    {% set json_data = load_data(path = docs::client_json_path(client_path= path), format="json") %}
+                    <tr class="table-row {% if loop.index is even %}even-row{% else %}odd-row{% endif %}">
+                        {% for field in client_fields %}
+                            <td class="table-cell">
+                                {% if field not in ["name", "language"] %}
+                                    {{ docs::boolean_to_checkmark(value=json_data[field]) }}
+                                {% else %}
+                                    {{ json_data[field] }}
+                                {% endif %}
+                            </td>
+                        {% endfor %}
+                    </tr>
+                {%- endfor %}
+            </tbody>
+        </table>
+    </div>
+{% endblock main_content %}