Adds valkey-json module commands documentation to the website. (#243)

One of the three PRs Required for module documentation to be included on
the website

Related PRs: 
valkey-io/valkey-json#42

Will wait for valkey-io/valkey-io.github.io#212
to het merged so we can use the framework to display documentation

We have merged the bloom changes in PR too as it depends on that, we
would only review the changes related to JSON for this PR

---------

Signed-off-by: zackcam <[email protected]>
Signed-off-by: Nikhil Manglore <[email protected]>
Signed-off-by: Roshan Khatri <[email protected]>
Signed-off-by: Nikhil Manglore <[email protected]>
Signed-off-by: Roshan Khatri <[email protected]>
Signed-off-by: Madelyn Olson <[email protected]>
Co-authored-by: zackcam <[email protected]>
Co-authored-by: KarthikSubbarao <[email protected]>
Co-authored-by: Nikhil Manglore <[email protected]>
Co-authored-by: Nikhil Manglore <[email protected]>
Co-authored-by: Madelyn Olson <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 6 people

Makefile

@@ -9,6 +9,8 @@ DATE ?= 2025-03-31
 # Path to the code repo.
 VALKEY_ROOT ?= ../valkey
 VALKEY_BLOOM_ROOT ?= ../valkey-bloom
+VALKEY_JSON_ROOT ?= ../valkey-json
+
 # Where to install man pages
 INSTALL_MAN_DIR ?= /usr/local/share/man
 
@@ -34,6 +36,10 @@ ifeq ("$(wildcard $(VALKEY_BLOOM_ROOT))","")
     $(info Valkey bloom variable pointed to nothing, skipping bloom filter commands)
 endif
 
+ifeq ("$(wildcard $(VALKEY_JSON_ROOT))","")
+    $(error Please provide the VALKEY_JSON_ROOT variable pointing to the valkey-json source code)
+endif
+
 ifeq ("$(shell which pandoc)","")
     $(error Please install pandoc)
 endif
@@ -58,9 +64,12 @@ endif
 
 documented_commands = $(wildcard commands/*.md)
 commands_json_files = $(wildcard $(VALKEY_ROOT)/src/commands/*.json)
+
 bloom_commands_json_files = $(wildcard $(VALKEY_BLOOM_ROOT)/src/commands/*.json)
+valkey_json_commands_json_files = $(wildcard $(VALKEY_JSON_ROOT)/src/commands/*.json)
 existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md) \
-                   $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md)
+                    $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md) \
+                    $(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md)
 
 topics   = $(wildcard topics/*)
 commands = $(filter $(existing_commands),$(documented_commands))
@@ -73,7 +82,8 @@ topics_pics = $(filter-out %.md,$(topics))
 # JSON files for the commands that have a .md file (excluding undocumented commands).
 json_for_documented_commands = \
     $(patsubst commands/%.md,$(VALKEY_ROOT)/src/commands/%.json,$(filter $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
-    $(patsubst commands/%.md,$(VALKEY_BLOOM_ROOT)/src/commands/%.json,$(filter $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md),$(commands)))
+    $(patsubst commands/%.md,$(VALKEY_BLOOM_ROOT)/src/commands/%.json,$(filter $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
+    $(patsubst commands/%.md,$(VALKEY_JSON_ROOT)/src/commands/%.json,$(filter $(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md),$(commands)))
 
 $(BUILD_DIR)/.commands-per-group.json: $(VALKEY_ROOT)/src/commands/. utils/build-command-groups.py | $(BUILD_DIR)
 	utils/build-command-groups.py $(json_for_documented_commands) > $@~~
@@ -187,13 +197,14 @@ $(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts)
 	 --version $(VERSION) --date $(DATE) \$< \
 	 | utils/links-to-man.py - | $(to_man) > $@
 $(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
+	$(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_JSON_ROOT)) 
 	$(eval FINAL_ROOT := $(firstword $(foreach root,$(VALKEY_ROOTS),$(if $(wildcard $(root)/src/commands/$*.json),$(root)))))
-	$(if $(FINAL_ROOT), \
+	$(if $(FINAL_ROOT),,$(eval FINAL_ROOT := $(lastword $(VALKEY_ROOTS))))
 		utils/preprocess-markdown.py --man --page-type command \
 		--version $(VERSION) --date $(DATE) \
 		--commands-per-group-json $(BUILD_DIR)/.commands-per-group.json \
 		--valkey-root $(FINAL_ROOT) $< \
-		| utils/links-to-man.py - | $(to_man) > $@)
+		| utils/links-to-man.py - | $(to_man) > $@
 $(MAN_DIR)/man5/%.5.gz: topics/%.md $(man_scripts)
 	utils/preprocess-markdown.py --man --page-type config \
 	 --version $(VERSION) --date $(DATE) $< \

README.md

@@ -7,13 +7,13 @@ for generating content for the website and man pages.
 
 This repo comes with a Makefile to build and install man pages.
 
-    make VALKEY_ROOT=path/to/valkey VALKEY_BLOOM_ROOT=path/to/valkey-bloom
+    make VALKEY_ROOT=path/to/valkey VALKEY_BLOOM_ROOT=path/to/valkey-bloom VALKEY_JSON_ROOT=path/to/valkey-json
     sudo make install INSTALL_MAN_DIR=/usr/local/share/man
 
 Prerequisites: GNU Make, Python 3, Python 3 YAML (pyyaml), Pandoc.
 Additionally, the scripts need access to the valkey code repo,
 where metadata files about the commands are stored. Additionally
-access to the valkey-bloom repo is optional.
+access to the valkey-bloom and valkey-json repos are optional.
 
 The pages are generated under `_build/man/` by default. The default install
 location is `/usr/local/share/man` (in the appropriate subdirectories).

commands/json.arrappend.md

@@ -0,0 +1,27 @@
+Append one or more values to the array values at the path.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRAPPEND  k1 $[*] '"c"'
+1) (integer) 1
+2) (integer) 2
+3) (integer) 3
+127.0.0.1:6379> JSON.GET k1
+"[[\"c\"],[\"a\",\"c\"],[\"a\",\"b\",\"c\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRAPPEND  k1 [-1] '"c"'
+(integer) 3
+127.0.0.1:6379> JSON.GET k1
+"[[],[\"a\"],[\"a\",\"b\",\"c\"]]"
+```

commands/json.arrindex.md

@@ -0,0 +1,28 @@
+Search for the first occurrence of a scalar JSON value in the arrays at the path.
+
+
+* Out of range errors are treated by rounding the index to the array's start and end.
+* If start > end, return -1 (not found).
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRINDEX k1 $[*] '"b"'
+1) (integer) -1
+2) (integer) -1
+3) (integer) 1
+4) (integer) 1
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '{"children": ["John", "Jack", "Tom", "Bob", "Mike"]}'
+OK
+127.0.0.1:6379> JSON.ARRINDEX k1 .children '"Tom"'
+(integer) 2
+```

commands/json.arrinsert.md

@@ -0,0 +1,32 @@
+Insert one or more values into the array values at path before the index.
+
+
+* Inserting at index 0 prepends to the array.
+* A negative index values is interpreted as starting from the end.
+* The index must be in the array's boundary.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRINSERT k1 $[*] 0 '"c"'
+1) (integer) 1
+2) (integer) 2
+3) (integer) 3
+127.0.0.1:6379> JSON.GET k1
+"[[\"c\"],[\"c\",\"a\"],[\"c\",\"a\",\"b\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRINSERT k1 . 0 '"c"'
+(integer) 4
+127.0.0.1:6379> JSON.GET k1
+"[\"c\",[],[\"a\"],[\"a\",\"b\"]]"
+```

commands/json.arrlen.md

@@ -0,0 +1,44 @@
+Get length of the array at the path.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], [\"a\"], [\"a\", \"b\"], [\"a\", \"b\", \"c\"]]'
+(error) SYNTAXERR Failed to parse JSON string due to syntax error
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k1 $[*]
+1) (integer) 0
+2) (integer) 1
+3) (integer) 2
+4) (integer) 3
+
+127.0.0.1:6379> JSON.SET k2 . '[[], "a", ["a", "b"], ["a", "b", "c"], 4]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k2 $[*]
+1) (integer) 0
+2) (nil)
+3) (integer) 2
+4) (integer) 3
+5) (nil)
+```
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k1 [*]
+(integer) 0
+127.0.0.1:6379> JSON.ARRLEN k1 $[3]
+1) (integer) 3
+
+127.0.0.1:6379> JSON.SET k2 . '[[], "a", ["a", "b"], ["a", "b", "c"], 4]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k2 [*]
+(integer) 0
+127.0.0.1:6379> JSON.ARRLEN k2 $[1]
+1) (nil)
+127.0.0.1:6379> JSON.ARRLEN k2 $[2]
+1) (integer) 2
+```

commands/json.arrpop.md

@@ -0,0 +1,34 @@
+Remove and return element at the index from the array. Popping an empty array returns null.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRPOP k1 $[*]
+1) (nil)
+2) "\"a\""
+3) "\"b\""
+127.0.0.1:6379> JSON.GET k1
+"[[],[],[\"a\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRPOP k1
+"[\"a\",\"b\"]"
+127.0.0.1:6379> JSON.GET k1
+"[[],[\"a\"]]"
+
+127.0.0.1:6379> JSON.SET k2 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRPOP k2 . 0
+"[]"
+127.0.0.1:6379> JSON.GET k2
+"[[\"a\"],[\"a\",\"b\"]]"
+```

commands/json.arrtrim.md

@@ -0,0 +1,34 @@
+Trim arrays at the path so that it becomes subarray [start, end], both inclusive.
+
+
+* If the array is empty, do nothing, return 0.
+* If start < 0, treat it as 0.
+* If end >= size (size of the array), treat it as size-1.
+* If start >= size or start > end, empty the array and return 0.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRTRIM k1 $[*] 0 1
+1) (integer) 0
+2) (integer) 1
+3) (integer) 2
+4) (integer) 2
+   127.0.0.1:6379> JSON.GET k1
+   "[[],[\"a\"],[\"a\",\"b\"],[\"a\",\"b\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '{"children": ["John", "Jack", "Tom", "Bob", "Mike"]}'
+OK
+127.0.0.1:6379> JSON.ARRTRIM k1 .children 0 1
+(integer) 2
+127.0.0.1:6379> JSON.GET k1 .children
+"[\"John\",\"Jack\"]"
+```

commands/json.clear.md

@@ -0,0 +1,18 @@
+Clear the arrays or objects at the path.
+
+## Examples
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], [0], [0,1], [0,1,2], 1, true, null, "d"]'
+OK
+127.0.0.1:6379>  JSON.CLEAR k1  $[*]
+(integer) 6
+127.0.0.1:6379> JSON.CLEAR k1  $[*]
+(integer) 0 
+127.0.0.1:6379> JSON.SET k2 . '{"children": ["John", "Jack", "Tom", "Bob", "Mike"]}'
+OK
+127.0.0.1:6379> JSON.CLEAR k2 .children
+(integer) 1
+127.0.0.1:6379> JSON.GET k2 .children
+"[]"
+```

commands/json.debug.md

@@ -0,0 +1,62 @@
+Report information. Supported subcommands are:
+
+
+* MEMORY <key> [path] - report memory usage in bytes of a JSON value. Path defaults to the root if not provided.
+* DEPTH <key> - report the maximum path depth of the JSON document.
+* FIELDS <key> [path] - report the number of fields at the specified document path. Path defaults to the root if not provided.
+  Each non-container JSON value counts as one field. Objects and arrays recursively count one field for each of their
+  containing JSON values. Each container value, except the root container, counts as one additional field.
+* HELP - print help messages of the command.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[1, 2.3, "foo", true, null, {}, [], {"a":1, "b":2}, [1,2,3]]'
+OK
+127.0.0.1:6379> JSON.DEBUG MEMORY k1 $[*]
+1) (integer) 16
+2) (integer) 16
+3) (integer) 19
+4) (integer) 16
+5) (integer) 16
+6) (integer) 16
+7) (integer) 16
+8) (integer) 50
+9) (integer) 64
+127.0.0.1:6379> JSON.DEBUG FIELDS k1 $[*]
+1) (integer) 1
+2) (integer) 1
+3) (integer) 1
+4) (integer) 1
+5) (integer) 1
+6) (integer) 0
+7) (integer) 0
+8) (integer) 2
+9) (integer) 3
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '{"firstName":"John","lastName":"Smith","age":27,"weight":135.25,"isAlive":true,"address":{"street":"21 2nd Street","city":"New York","state":"NY","zipcode":"10021-3100"},"phoneNumbers":[{"type":"home","number":"212 555-1234"},{"type":"office","number":"646 555-4567"}],"children":[],"spouse":null}'
+OK
+127.0.0.1:6379> JSON.DEBUG MEMORY k1
+(integer) 632
+127.0.0.1:6379> JSON.DEBUG MEMORY k1 .phoneNumbers
+(integer) 166
+
+127.0.0.1:6379> JSON.DEBUG FIELDS k1
+(integer) 19
+127.0.0.1:6379> JSON.DEBUG FIELDS k1 .address
+(integer) 4
+```
+
+```bash
+127.0.0.1:6379> JSON.DEBUG HELP
+1) JSON.DEBUG MEMORY <key> [path] - report memory size (bytes) of the JSON element. Path defaults to root if not provided.
+2) JSON.DEBUG FIELDS <key> [path] - report number of fields in the JSON element. Path defaults to root if not provided.
+3) JSON.DEBUG DEPTH <key> - report depth of JSON doc.
+3) JSON.DEBUG HELP - print help message.
+```