Adding functionality for the bloom module to have its commands displayed on the Valkey website (#212)

Related PR's
Bloom repo json command files:
valkey-io/valkey-bloom#47
Valkey-doc repo: valkey-io/valkey-doc#233

### Description
This PR will allow set the framework so that modules can have their
commands displayed on the valkey website (By adding the bloom module
commands in a way that can be easily expanded on). I have tried to make
this future proof by using a for loop on the `commands.html` page which
can be expanded by just adding any new folders we want to pull commands
from. For the `command-page.html` I have used an array to hold the data
from the multiple folders with commands and then get the first
occurrence that isn't empty (i.e the command belongs to that folder).
This will keep ability so that if the command doesn't exist we still
have the same fallback.

Updated the `init-commands.sh` to create a link for the bloom commands
as well and take in the bloom repository.

I have updated the README as well to include the new repo that will be
needed for the commands and the information change associated with now
expecting commands from the bloom repo.

Lastly updated the github workflow as well to also now build and take in
the bloom repo

**For screenshots of the new documentation the two pr's above
(valkey-io/valkey-doc#233 and
valkey-io/valkey-bloom#47) have screenshots of
all sections being added**

### 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: zackcam <[email protected]>

Author: zackcam

.github/workflows/zola-deploy.yml

@@ -33,12 +33,19 @@ jobs:
         with:
           repository: valkey-io/valkey
           path: valkey
-          
+
+      - name: Checkout valkey-bloom
+        uses: actions/checkout@v4
+        with:
+            repository: valkey-io/valkey-bloom
+            path: valkey-bloom
+
       - name: Init commands, topics and clients
         run: |
           cd website
           ./build/init-topics-and-clients.sh ../valkey-doc/topics ../valkey-doc/clients
-          ./build/init-commands.sh ../valkey-doc/commands ../valkey/src/commands
+          ./build/init-commands.sh ../valkey-doc/commands ../valkey/src/commands ../valkey-bloom/src/commands
+
       - name: Build only
         uses: shalzz/[email protected]
         env:

.gitignore

@@ -12,3 +12,4 @@ _site
 _data/groups.json
 _data/resp2_replies.json
 _data/resp3_replies.json
+_data/modules.json

README.md

@@ -1,7 +1,7 @@
 # Valkey.io website
 
 This repo contains the source for the valkey.io website (build scripts, template, blog posts, stylesheets, etc.).
-The build integrates content from [`valkey-io/valkey-doc`](https://github.com/valkey-io/valkey-doc) and the commands definitions from [`valkey-io/valkey`](https://github.com/valkey-io/valkey) (see [Build Locally](#build-locally) below for more details).
+The build integrates content from [`valkey-io/valkey-doc`](https://github.com/valkey-io/valkey-doc) and the commands definitions from [`valkey-io/valkey`](https://github.com/valkey-io/valkey) and [`valkey-io/valkey-bloom`](https://github.com/valkey-io/valkey-bloom) (see [Build Locally](#build-locally) below for more details).
 
 ## Contributing
 
@@ -63,8 +63,8 @@ Commit your changes to your local copy of `valkey-io/valkey-doc`.
 
 ### Building the command reference
 
-The command reference (i.e. `/commands/set/`, `/commands/get/`, `/commands/lolwut/`) sources information from `valkey-io/valkey`, and `valkey-io/valkey-doc`.
-`valkey-io/valkey` provides the command metadata (items like computational complexity, version history, arguments, etc) whilst `valkey-io/valkey-doc` provides the command description and the command reply.
+The command reference (i.e. `/commands/set/`, `/commands/get/`, `/commands/lolwut/`) sources information from `valkey-io/valkey`, `valkey-io/valkey-bloom`, and `valkey-io/valkey-doc`.
+`valkey-io/valkey` and `valkey-io/valkey-bloom` provides the command metadata (items like computational complexity, version history, arguments, etc) whilst `valkey-io/valkey-doc` provides the command description and the command reply.
 
 ```mermaid
 flowchart TD
@@ -75,13 +75,13 @@ flowchart TD
     H --> J[Files: /resp2_replies.json,<br/>/resp3_replies.json] --> Z[Command Reply]
 ```
 
-Let's say that this repo and your local copy of `valkey-io/valkey-doc` and `valkey-io/valkey` reside in the same directories.
+Let's say that this repo and your local copy of `valkey-io/valkey-doc`, `valkey-io/valkey-bloom` and `valkey-io/valkey` reside in the same directories.
 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 command.
-./build/init-commands.sh ../valkey-doc/commands ../valkey/src/commands
+./build/init-commands.sh ../valkey-doc/commands ../valkey/src/commands ../valkey-bloom/src/commands
 ```
 
 Then, restart Zola.

build/init-commands.sh

@@ -24,20 +24,30 @@ if [ ! -d "$2" ]; then
     exit 1
 fi
 
+if [ ! -d "$3" ]; then
+    echo "The bloom module command JSON directory must exist and be a valid path"
+    exit 1
+fi
+
 ln -s $1 ./build-command-docs
 ln -s $2 ./build-command-json
-
+ln -s $3 ./build-bloom-command-json
 for fname in $(find $1 -maxdepth 1  -iname "*.md")
 do
     base=${fname##*/}
     command=${base%.*}
     command_upper=$(awk '{ print toupper($0) }' <<< $command)
     if [[ "$command" != "index" ]]; then 
+        if [ -f "$2/$command.json" ]; then
+            metadata_path="/commands/$command.json in the 'valkey' repo"
+        elif [ -f "$3/$command.json" ]; then
+            metadata_path="/commands/$command.json in the 'valkey-bloom' repo"
+        fi
         cat << EOF > "./content/commands/$command.md"
 +++
 # This is a generated stub file.
 # To edit the command description see /commands/$command.md in the 'valkey-doc' repo
-# The command metadata is generated from /src/$command.json in the 'valkey' repo
+# The command metadata is generated from $metadata_path
 aliases = ["/commands/$command_upper/"]
 +++
 EOF
@@ -46,7 +56,7 @@ done
 
 echo "Command stub files created."
 
-for datafile in groups.json resp2_replies.json resp3_replies.json; do
+for datafile in groups.json resp2_replies.json resp3_replies.json modules.json; do
     ln -s "../${1}/../${datafile}" "./_data/${datafile}"
 
     echo "Created link to ${datafile}"

config.toml

@@ -21,6 +21,7 @@ highlight_code = true
 [extra]
 command_description_path = "../build-command-docs/"
 command_json_path = "../build-command-json/"
+command_bloom_json_path = "../build-bloom-command-json/"
 client_json_path = "../build-clients/"
 doc_topic_path = "../build-topics/"
 

templates/command-page.html

@@ -7,7 +7,13 @@
 {% set upper_slug = page.slug | upper %}
 
 {% set command_description = load_data(path=config.extra.command_description_path ~ page.slug ~ ".md", required= false) %}
-{% set command_data = load_data(path= commands::command_json_path(slug= page.slug), required= false) %}
+{% set command_sources = [
+    load_data(path= commands::command_json_path(slug= page.slug), required= false),
+    load_data(path= commands::command_bloom_json_path(slug= page.slug), required= false)
+] %}
+
+{% set command_data = command_sources | filter(attribute="") | first %}
+
 {% if command_data %}
     {% set command_obj_name = commands::command_obj_name(command_data= command_data) %}
     {% set command_data_obj = command_data[command_obj_name] %} 
@@ -48,13 +54,25 @@
         <dd>{{ command_data_obj.complexity }}</dd>
     <dl>
     {% endif %}
+    {% if command_data_obj.module_since %}
+    <dl>
+        {% if "bf." in page.slug  %} 
+            {% set module_reply = load_data(path="../_data/modules.json", required=false) -%}
+            <dt>Module:</dt>
+            <dd><a href={{module_reply.valkey_bloom.repo}}>{{module_reply.valkey_bloom.name}}</a></dd>
+        {% endif %}
+    <dl>
+    <dl>
+        <dt>Since module version:</dt>
+        <dd>{{ command_data_obj.module_since }}</dd>
+    <dl>
+    {% endif %}
     {% if command_data_obj.since %}
     <dl>
         <dt>Since:</dt>
         <dd>{{ command_data_obj.since }}</dd>
     <dl>
     {% endif %}
-
     </dl>
 
 {% else %}

templates/commands.html

@@ -16,23 +16,27 @@
 </div>
 
 {% for page in section.pages %}
-    {% set command_data = load_data(path= commands::command_json_path(slug= page.slug), required= false) %}
-    {% if command_data %}
-        {% set command_obj_name = commands::command_obj_name(command_data= command_data) %}
-        {% set command_data_obj = command_data[command_obj_name] %}
-        {% set command_display = command_obj_name %}
-        {% if command_data_obj.container %}
-            {% set command_display = command_data_obj.container ~ " " ~ command_display %}
+    {% for json_path in [
+        commands::command_json_path(slug=page.slug),
+        commands::command_bloom_json_path(slug=page.slug)
+    ] %}
+        {% set command_data = load_data(path= json_path, required= false) %}
+        {% if command_data %}
+            {% set command_obj_name = commands::command_obj_name(command_data= command_data) %}
+            {% set command_data_obj = command_data[command_obj_name] %}
+            {% set command_display = command_obj_name %}
+            {% if command_data_obj.container %}
+                {% set command_display = command_data_obj.container ~ " " ~ command_display %}
+            {% endif %}
+            {% set command_entry = [
+                command_display,
+                page.permalink | safe, 
+                command_data_obj.summary,
+                command_data_obj.group
+            ] %}
+            {% set_global commands_entries = commands_entries | concat(with= [ command_entry ]) %}
         {% endif %}
-
-        {% set command_entry = [
-            command_display,
-            page.permalink | safe, 
-            command_data_obj.summary,
-            command_data_obj.group
-        ] %}
-        {% set_global commands_entries = commands_entries | concat(with= [ command_entry ]) %}
-    {% endif %}
+    {% endfor %}
 {% endfor %}
 {% set_global grouped = commands_entries | sort(attribute="3") | group_by(attribute="3") %}
 

templates/macros/command.html

@@ -52,6 +52,10 @@
 {{config.extra.command_json_path }}{{ slug }}.json
 {%- endmacro load_command_json -%}
 
+{%- macro command_bloom_json_path(slug) -%}
+{{config.extra.command_bloom_json_path }}{{ slug }}.json
+{%- endmacro load_bloom_command_json -%}
+
 {%- macro fix_links(content) -%}
 {{ content
     | regex_replace(pattern=`\]\(\.\./topics/(?P<fname>.*?).md#(?P<hash>.*?)\)`, rep=`](/topics/$fname#$hash)`)