parsing the valkey command JSON files

stockholmux commented 3 months ago

Description

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)

Why so many files?

As you can see, this is a massive amount of files.

To achieve the same URL structure as the previous site (e.g. /commands/set/), I need to have a single stub file (auto-generated by the bash file) that tells Jekyll to create and render the page from the data command JSON files. IMHO, this should probably not be committed to the repo, but rather generated on build and .gitignored. Undoing the last commit would re-enable that, if the current (and future) build infrastructure can support running the bash script on build.

What's the status of the command parsing?

The command parsing in this PR is acceptable but certainly not perfect. I've cross checked it vs a few other sources and it looks good enough for someone to not be lead astray, but there are edges that don't look right. Given that there 400 commands, I've haven't personally checked everyone of them, but I tried to do a sampling check of similar commands to see how it looks it look wrong-ity wrong.

Submodules

This PR uses submodules to valkey-doc and valkey. This is good as a stop-gap solution but I'm not certain this is the best long term solution. Like the node about the number of files, I think these should be pullled in on-build.

What else is missing?

Gobs.

It doesn't currently handle ACL categories and RESP reply sections.
Similar sites seem to have more details on deprecation that don't appear to be present in the commands nor docs.
The listing is bare-bones: it would be nice to have categories or some sort of better organization

But optimizing for good/fast not perfect, I think this PR is a decent place to start.

What's next?

Working with valkey-doc, each command needs human eyes on it. I'd also like to figure out how we're handling non-Valkey versions in place.

Issues Resolved

n/a

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.

zuiderkwast commented 3 months ago

I fail to see why we have to reinvent this wheel, when there is an existing way to do it that we can just clone.

Redict have their website up and running using Hugo: https://redict.io

stockholmux commented 3 months ago

@zuiderkwast redict-io is GNU Free Documentation License, this repo is BSD-3 Clause.

zuiderkwast commented 3 months ago

They cloned it from https://github.com/redis/redis-website apparently. That one is Apache 2.

Our website can be Apache 2 I guess? I can't see a reason we must stick to a BSD for the website. Do you?

zuiderkwast commented 3 months ago

Btw, this license is just for the rendering templating. The content (valkey-doc) is Creative Commons Attribution-ShareAlike 4.0, just like redis-doc.

stockholmux commented 3 months ago

@zuiderkwast The best place to discuss the license of this repo is probably not in this draft PR.

madolson commented 2 months ago

I missed the fact the top comment said draft only, so probably shouldn't have clicked merge.

stockholmux commented 2 months ago

@madolson lol - that was my bad. What a comedy. 😓

I switched it out of draft mode this afternoon and didn't change the PR. I think it's fine to merge (or remerge).

madolson commented 2 months ago

As long as you don't mind, I looked through everything and the conversation and looked OK to me. I wanted to see it on the temp website.

stockholmux commented 2 months ago

Hard to say, but looks like the submodules didn't get pulled in to the preview site. I can see the commands page (which should be a list of commands) and the individual commands pages, but they don't have anything on them.

They should look something like this:

@AMoo-Miki Can you take a look workflow that is building the preview site?

valkey-io / valkey-io.github.io