Adds a clients overview page #166

liorsve · 2024-11-25T18:47:56Z

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 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
Dependent on this PR being merged - #164

Check List

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.

stockholmux

It needs some adjustments and I have some general approach questions but quite good work on this!

One general comment that I couldn't stick anywhere: Make sure your final PR includes README instructions on how this works.

build/init-topics.sh

config.toml

stockholmux · 2024-11-26T15:00:55Z

config.toml

@@ -48,4 +49,16 @@ publish_hold = [
    "/topics/internals/",
    "/topics/protocol/",
    "/topics/rdd/"
+]
+
+recommended_clients_paths = [


Two questions here:

config.toml is a site-level configuration (e.g. included on every page). Is there a better place for this data? I would guess either the macro can load a arbitrary file or include a recommended flag in the JSON file itself. It could also be stored in custom frontmatter (see added custom frontmatter for topics, override for about/history #167), which might be a flexible alternative to present different recommendations on different pages.

How was the 'recommendation' list arrived at?

Seems like the custom frontmatter is the best option here as it would also help with avoiding checking for slug

about the list - Introduce Valkey client overview valkey-doc#164 (comment)

Alright @liorsve, we're dependent on #164 make sense.

stockholmux · 2024-11-26T15:04:34Z

templates/client_feature_table.html

+<hr/>
+<h2>Feature Comparison Table</h2>
+{% if page.slug == "valkey-clients" %}
+    <div style="margin: 20px 0; padding: 10px; border: 2px solid #dcdcdc; background-color: #f9f9f9; border-radius: 5px; overflow-x: auto;">


please use proper CSS classes throughout and define styles with SASS.

Inline styles are difficult to maintain and make consistent style changes across the site.

Added, I put it in the _valkey.scss file - hope this is the right place?

config.toml

stockholmux · 2024-11-26T15:16:47Z

templates/docs-page.html

@@ -38,11 +38,14 @@ <h1 class="page-title">Documentation: {{ frontmatter_title }}</h1>
 {% else %}
    {{ content_with_fixed_links | markdown | safe }}
 {% endif %}
+{% if page.slug == "valkey-clients" %}


I'm unclear why page.slug is being checked here and on client_feature_table.html.

On the topic of comparing for the page slug: Is there are more elegant way of doing this? Right now it ties it to a specific page - what if we wanted to include the table on other pages? Ideally this could be achieved without touching the template, only the content.

No reason, just forgot to remove it from previous versions. Removed it now.
About comparing for slug, I tried to avoid this and couldn't find another solution, but now that I see #167 , I could maybe create a custom frontmatter with a custom template for this topic that would override the default topic template, which would render all client specific content (the table, but also all of the client list section as per this comment). Does this sound better?

Yeah, so what we can do is add some flag to [extra] section of the front matter (maybe include_client_table) and the template checks for that and adds it. Lots of ways to do this, but the general approach is a lot more flexible.

You could even some configuration, e.g. show only python clients or clients that support some feature. Definitely don't need that now, but think about it when implementing something to replace the slug comparison.

So what I merged (before seeing your comment) in order to avoid changing thedocs-page.html template, is to just override it completely with a custom template that renders everything that needs to be rendered from jsons. Then no flags/changes to docs-page.html are needed. WDYT? @stockholmux

liorsve · 2024-12-01T17:08:03Z

cherry-picked added custom frontmatter for topics, override for about/history #167
added a custom frontmatter that overrides the default topics template, and contains the list of recommended clients' paths
created a new custom template for the clients page topic, which renders all client specific content from the json client files in valkey-doc/clients (github url, installation and description), and includes the feature comparison table.

zuiderkwast · 2024-12-17T23:00:11Z

I fail to see in the diff what the URL of this page will be.

I suggest we put it under the root, at https://valkey.io/clients/. It doesn't really belong under topics.

We already have links to ../clients/ from topics and commands pages, because the corresponding page in the old redis website had this location too. By keeping this, we don't need to update the links in the doc repo.

I don't have a strong opinion about this though. If there is another plan, then we can just update the links in the docs to point to the right path, because I prefer that they make sense for doc writers.

liorsve · 2024-12-18T16:10:50Z

@zuiderkwast I have no problem moving this, we haven't discussed it and I just put it in topics as a starting point for discussion, so we'll have some kind of visualization. Also it would simplify things if it's not under topics, cause then maybe I won't have to use the topic custom frontmatter PR. Where do you suggest placing this on the website?

stockholmux

This belongs in the top nav documentation drop down and on the /docs/ page as well. But the url should be top level (e.g. valkey.io/clients

stockholmux · 2025-01-02T19:52:38Z

templates/client-list.html

+                    {% set client = load_data(path = docs::client_json_path(client_path= path), format="json") %}
+                    {% if client.language == language %}
+                    <div class="client-item">
+                        <h3>{{ client.name }}</h3>


needs a id with slugified client.name as to allow for deep linking to a specific client.

Signed-off-by: lior sventitzky <[email protected]>

…d paths Signed-off-by: lior sventitzky <[email protected]>

…link to clients folder Signed-off-by: lior sventitzky <[email protected]>

Signed-off-by: lior sventitzky <[email protected]>

liorsve · 2025-01-09T14:25:19Z

Summarizing the big changes I added -

The page moved from being a topic to the top nav docs, called "Client Libraries". With url valkey.io/clients.
Because this is not a topic anymore and it requires creating a symlink to the clients folder in docs, it needs to be included in the shell script. But it's only for creating the symlink and it doesn't create any stub files like the current init-topics.sh does for topics, so it's a relatively little addition. So I though it's better to avoid adding a separate init-clients.sh file, and instead modify init-topics.sh to be init-topics-and-clients, and have it expect the path to topics as its first arg, and the path to clients as its second arg. README was updated accordingly.
I moved here the markdown content for this page (i.e. explanations about the different client features), which previously was loaded from topics in the docs repo.
Updated clients paths according to the change in structure of the clients folder in the docs repo PR - #164.

Signed-off-by: lior sventitzky <[email protected]>

liorsve mentioned this pull request Nov 25, 2024

Introduce Valkey client overview valkey-io/valkey-doc#164

Open

stockholmux requested changes Nov 26, 2024

View reviewed changes

zuiderkwast mentioned this pull request Dec 17, 2024

Placeholder pages for modules and clients #177

Open

stockholmux requested changes Jan 2, 2025

View reviewed changes

liorsve changed the title ~~Adds a client feature comparison table for a future clients overview page~~ Adds a clients overview page Jan 7, 2025

liorsve added 8 commits January 9, 2025 13:50

added table logic and template

9d91008

Signed-off-by: lior sventitzky <[email protected]>

added saas for table, other fixes according to review

8328c7b

Signed-off-by: lior sventitzky <[email protected]>

created a template for clients page topic with a custom frontmatter

fbd95a9

Signed-off-by: lior sventitzky <[email protected]>

updated table to include a package size placeholder

8cbc1bd

Signed-off-by: lior sventitzky <[email protected]>

moved page to docs, added markdown content (moved from docs) and fixe…

19e54c1

…d paths Signed-off-by: lior sventitzky <[email protected]>

updated 'init-topics.sh' to 'init-topics-and-clients.sh' to start sym…

77c1ca4

…link to clients folder Signed-off-by: lior sventitzky <[email protected]>

additional changes to move from topics to docs

020fa88

Signed-off-by: lior sventitzky <[email protected]>

updated style, changed rendering to load from path

8e69fbc

Signed-off-by: lior sventitzky <[email protected]>

liorsve force-pushed the website-clients-page branch from f8ee2d8 to 8e69fbc Compare January 9, 2025 13:55

small fixes to style and markdown

e0ba0c3

Signed-off-by: lior sventitzky <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds a clients overview page #166

Adds a clients overview page #166

liorsve commented Nov 25, 2024 •

edited

Loading

stockholmux left a comment

stockholmux Nov 26, 2024

liorsve Dec 1, 2024

stockholmux Dec 4, 2024

stockholmux Nov 26, 2024

liorsve Nov 28, 2024

stockholmux Nov 26, 2024

liorsve Nov 28, 2024

stockholmux Dec 4, 2024

liorsve Dec 16, 2024 •

edited

Loading

liorsve commented Dec 1, 2024 •

edited

Loading

zuiderkwast commented Dec 17, 2024

liorsve commented Dec 18, 2024

stockholmux left a comment

stockholmux Jan 2, 2025

liorsve Jan 12, 2025

liorsve commented Jan 9, 2025

Adds a clients overview page #166

Are you sure you want to change the base?

Adds a clients overview page #166

Conversation

liorsve commented Nov 25, 2024 • edited Loading

Description

How it works -

Issues Resolved

Check List

stockholmux left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liorsve Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

liorsve commented Dec 1, 2024 • edited Loading

zuiderkwast commented Dec 17, 2024

liorsve commented Dec 18, 2024

stockholmux left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liorsve commented Jan 9, 2025

liorsve commented Nov 25, 2024 •

edited

Loading

liorsve Dec 16, 2024 •

edited

Loading

liorsve commented Dec 1, 2024 •

edited

Loading