parsing the valkey command JSON files (draft only) (#8)

Initial work to parse the command json files from Valkey. * Add submodules for valkey-io/valkey and valkey-io/valkey-doc * Adds a bash script to generate stub files for all the commands * Adds recursive argument template * Adds a command layout (e.g. template for each command) * Two tweaks to SCSS to make it look readable and consistent * Adds a file to render the command listing * Adds all command stubs (generated by the bash script) Signed-off-by: Kyle J. Davis <[email protected]>
valkey-io · Apr 8, 2024 · 53318a5 · 53318a5
1 parent a6a43bd
commit 53318a5
Show file tree

Hide file tree

Showing 402 changed files with 2,114 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,5 @@ _site
 .jekyll-metadata
 vendor
 .DS_Store
+/_data/commands/
+/_includes/commands/
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,6 @@
+[submodule "_submodules/valkey"]
+	path = _submodules/valkey
+	url = https://github.com/valkey-io/valkey
+[submodule "_submodules/valkey-doc"]
+	path = _submodules/valkey-doc
+	url = https://github.com/valkey-io/valkey-doc
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -13,6 +13,7 @@ GEM
     eventmachine (1.2.7)
     ffi (1.16.3)
     forwardable-extended (2.6.0)
+    google-protobuf (3.25.3-arm64-darwin)
     google-protobuf (3.25.3-x86_64-darwin)
     http_parser.rb (0.8.0)
     i18n (1.14.4)
@@ -33,6 +34,7 @@ GEM
       safe_yaml (~> 1.0)
       terminal-table (>= 1.8, < 4.0)
       webrick (~> 1.7)
+    jekyll-datapage-generator (1.4.0)
     jekyll-feed (0.15.1)
       jekyll (>= 3.7, < 5.0)
     jekyll-last-modified-at (1.3.0)
@@ -73,6 +75,8 @@ GEM
     rouge (3.26.0)
     ruby-link-checker (0.2.0)
     safe_yaml (1.0.5)
+    sass-embedded (1.69.5-arm64-darwin)
+      google-protobuf (~> 3.23)
     sass-embedded (1.69.5-x86_64-darwin)
       google-protobuf (~> 3.23)
     terminal-table (3.0.2)
@@ -83,11 +87,13 @@ GEM
     webrick (1.8.1)
 
 PLATFORMS
+  arm64-darwin-22
   x86_64-darwin-19
   x86_64-darwin-21
 
 DEPENDENCIES
   jekyll (~> 4.3.2)
+  jekyll-datapage-generator
   jekyll-feed (~> 0.12)
   jekyll-last-modified-at
   jekyll-paginate

diff --git a/_build/commands.sh b/_build/commands.sh
@@ -0,0 +1,26 @@
+#!/bin/bash
+# this bash script generates stubs directories/index files based on the command JSONs
+
+COMMANDS="./_data/commands/latest/*.json"
+for f in $COMMANDS
+do
+    COMMAND=$(basename -- "$f")
+    COMMAND_FNAME=${COMMAND%.*}
+    DESCRIPTION_FNAME="./_includes/commands/latest/${COMMAND_FNAME}.md"
+    echo $DESCRIPTION_FNAME
+    mkdir ./commands/$COMMAND_FNAME
+    if [ -f "$DESCRIPTION_FNAME" ]; then
+        echo "Exists, ${DESCRIPTION_FNAME}"
+        DESCRIPTION_FRONTMATTER="description: ${COMMAND_FNAME}.md"
+    else 
+        DESCRIPTION_FRONTMATTER=""
+    fi
+
+    cat << EOF > ./commands/$COMMAND_FNAME/index.html
+---
+layout: command
+title: $COMMAND_FNAME
+$DESCRIPTION_FRONTMATTER
+---
+EOF
+done
diff --git a/_includes/command/arguments.html b/_includes/command/arguments.html
@@ -0,0 +1,26 @@
+{% for arguments in include.arguments_array %}
+
+    {% capture arguments_str %}    
+        {% if arguments.optional ==  true %}[{% elsif arguments.type == "oneof"%}〈{%endif%}
+        {% if arguments.type !=  "pure-token" and arguments.token %}
+            {{ arguments.token }}
+        {% endif %}
+        {% if arguments.type !=  "block"  and arguments.type !=  "oneof" %}
+            {{ arguments.name }}
+        {% endif %}
+
+        {% if arguments.type == "oneof" %}
+           {%  include command/arguments.html arguments_array=arguments.arguments separator="|" %}
+        {% else %}
+            {%  include command/arguments.html arguments_array=arguments.arguments %}
+        {% endif  %}
+        {% if include.separator == "|" and forloop.last == false %} | {% endif %}
+
+        {% if arguments.optional ==  true %}]{% elsif arguments.type == "oneof"%}〉{%endif%}
+    {% endcapture %}
+    {{ arguments_str }}
+
+    {% if arguments.multiple %}
+        [ {{ arguments_str }} ...]
+    {% endif %}
+{% endfor %}
diff --git a/_layouts/command.html b/_layouts/command.html
@@ -0,0 +1,59 @@
+---
+layout: default
+---
+
+{% for command in site.data.commands.latest[page.title] %}
+    {% assign command_name = command[0] %}
+    {% assign command_lower =  command[0] | downcase %}
+    {% assign command_details = command[1] %} 
+    {% capture usage %}{{command_details.container }} {{ command_name }} {%  include command/arguments.html arguments_array=command_details.arguments %}{% endcapture %}
+    <h1 class="page-title">{{command_details.container }} {{ command_name }}
+        {% if command_details.doc_flags contains "DEPRECATED" %}
+            <small>Deprecated</small>
+        {% endif %}
+    </h1>
+    <div class="width-limiter">
+        <main class="container">
+
+            <dl>
+                <dt>Usage:</dt>
+                <dd><code>{{usage}}</code></dd>
+            </dl>
+            <dl>
+                <dt>Complexity:</dt>
+                <dd>{{ command_details.complexity }}</dd>
+            </dl>
+            <dl>
+                <dt>Since:</dt>
+                <dd>{{ command_details.since }}</dd>
+            </dl>
+            {% if page.description %}
+                {% assign command_description_file = "commands/latest/FILE" | replace: "FILE", page.description %}
+                {% capture description %}{% include {{ command_description_file }}  %}{% endcapture %}
+                {{ description | replace: "@examples", "## Examples" | markdownify }}
+            {% endif %}
+            {% if command_details.history %}
+                <h3>History</h3>
+                <table>
+                    <thead>
+                        <tr>
+                            <th>Version</th>
+                            <th>Change</th>
+                        </tr>
+                    </thead>
+
+                    <tbody>
+                        {% for history_line in command_details.history %}
+                        <tr>
+                            <td>{{history_line[0]}}</td>
+                            <td>{{history_line[1]}}</td>
+                        </tr>
+                        {% endfor %}
+                    </tbody>
+
+                </table>
+            {% endif %}
+        </main>
+    </div>
+
+{% endfor %}
diff --git a/_sass/_valkey.scss b/_sass/_valkey.scss
@@ -247,7 +247,7 @@ p {
   max-width: var(--max-width);
   background: #fff;
   margin: 0 auto;
-  padding: 4rem;
+  padding: 2rem;
   color: $body-text-color;
   border-bottom: 10px solid $body-heading-color;
   font-weight: 300;
@@ -471,4 +471,12 @@ aside {
       padding: .5rem 1rem;
     }
   }
+}
+
+.command-entry {
+  border-bottom: 1px dotted $line;
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
+  padding-top: 1rem;
+  padding-bottom: 1rem;
 }
diff --git a/_submodules/valkey b/_submodules/valkey
diff --git a/_submodules/valkey-doc b/_submodules/valkey-doc
diff --git a/commands/acl-cat/index.html b/commands/acl-cat/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-cat
+description: acl-cat.md
+---
diff --git a/commands/acl-deluser/index.html b/commands/acl-deluser/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-deluser
+description: acl-deluser.md
+---
diff --git a/commands/acl-dryrun/index.html b/commands/acl-dryrun/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-dryrun
+description: acl-dryrun.md
+---
diff --git a/commands/acl-genpass/index.html b/commands/acl-genpass/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-genpass
+description: acl-genpass.md
+---
diff --git a/commands/acl-getuser/index.html b/commands/acl-getuser/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-getuser
+description: acl-getuser.md
+---
diff --git a/commands/acl-help/index.html b/commands/acl-help/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-help
+description: acl-help.md
+---
diff --git a/commands/acl-list/index.html b/commands/acl-list/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-list
+description: acl-list.md
+---
diff --git a/commands/acl-load/index.html b/commands/acl-load/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-load
+description: acl-load.md
+---
diff --git a/commands/acl-log/index.html b/commands/acl-log/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-log
+description: acl-log.md
+---
diff --git a/commands/acl-save/index.html b/commands/acl-save/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-save
+description: acl-save.md
+---
diff --git a/commands/acl-setuser/index.html b/commands/acl-setuser/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-setuser
+description: acl-setuser.md
+---
diff --git a/commands/acl-users/index.html b/commands/acl-users/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-users
+description: acl-users.md
+---
diff --git a/commands/acl-whoami/index.html b/commands/acl-whoami/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl-whoami
+description: acl-whoami.md
+---
diff --git a/commands/acl/index.html b/commands/acl/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: acl
+description: acl.md
+---
diff --git a/commands/append/index.html b/commands/append/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: append
+description: append.md
+---
diff --git a/commands/asking/index.html b/commands/asking/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: asking
+description: asking.md
+---
diff --git a/commands/auth/index.html b/commands/auth/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: auth
+description: auth.md
+---
diff --git a/commands/bgrewriteaof/index.html b/commands/bgrewriteaof/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bgrewriteaof
+description: bgrewriteaof.md
+---
diff --git a/commands/bgsave/index.html b/commands/bgsave/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bgsave
+description: bgsave.md
+---
diff --git a/commands/bitcount/index.html b/commands/bitcount/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bitcount
+description: bitcount.md
+---
diff --git a/commands/bitfield/index.html b/commands/bitfield/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bitfield
+description: bitfield.md
+---
diff --git a/commands/bitfield_ro/index.html b/commands/bitfield_ro/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bitfield_ro
+description: bitfield_ro.md
+---
diff --git a/commands/bitop/index.html b/commands/bitop/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bitop
+description: bitop.md
+---
diff --git a/commands/bitpos/index.html b/commands/bitpos/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bitpos
+description: bitpos.md
+---
diff --git a/commands/blmove/index.html b/commands/blmove/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: blmove
+description: blmove.md
+---
diff --git a/commands/blmpop/index.html b/commands/blmpop/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: blmpop
+description: blmpop.md
+---
diff --git a/commands/blpop/index.html b/commands/blpop/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: blpop
+description: blpop.md
+---
diff --git a/commands/brpop/index.html b/commands/brpop/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: brpop
+description: brpop.md
+---
diff --git a/commands/brpoplpush/index.html b/commands/brpoplpush/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: brpoplpush
+description: brpoplpush.md
+---
diff --git a/commands/bzmpop/index.html b/commands/bzmpop/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bzmpop
+description: bzmpop.md
+---
diff --git a/commands/bzpopmax/index.html b/commands/bzpopmax/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bzpopmax
+description: bzpopmax.md
+---
diff --git a/commands/bzpopmin/index.html b/commands/bzpopmin/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: bzpopmin
+description: bzpopmin.md
+---
diff --git a/commands/client-caching/index.html b/commands/client-caching/index.html
@@ -0,0 +1,5 @@
+---
+layout: command
+title: client-caching
+description: client-caching.md
+---