diff --git a/build/local_examples.py b/build/local_examples.py index 20ac1dd2f..24bb650e6 100644 --- a/build/local_examples.py +++ b/build/local_examples.py @@ -10,10 +10,8 @@ """ import os -import glob import shutil import logging -from typing import Dict, Any from components.example import Example from components.util import mkdir_p @@ -89,61 +87,71 @@ def process_local_examples(local_examples_dir: str = 'local_examples', if os.path.exists(examples_json): examples_data = load_dict(examples_json) - # Process each file in local_examples directory - for filename in os.listdir(local_examples_dir): - source_file = os.path.join(local_examples_dir, filename) - - if not os.path.isfile(source_file): - continue - - # Get language from file extension - language = get_language_from_extension(filename) - if not language: - logging.warning(f"Unknown file extension for: {filename}") - continue - - # Get example ID from file content - example_id = get_example_id_from_file(source_file) - if not example_id: - logging.warning(f"No EXAMPLE: header found in {filename}") - continue - - logging.info(f"Processing local example: {example_id} ({language})") - - # Create target directory - target_dir = os.path.join(examples_dir, example_id) - mkdir_p(target_dir) - - # Initialize example data - if example_id not in examples_data: - examples_data[example_id] = {} - - # Copy file to target directory with local_ prefix - base_name = os.path.splitext(filename)[0] - ext = os.path.splitext(filename)[1] - target_filename = f"local_{base_name}{ext}" - target_file = os.path.join(target_dir, target_filename) - shutil.copy2(source_file, target_file) - - # Process with Example class - example = Example(language, target_file) - - # Get client name - client_name = get_client_name_from_language(language) - - # Create metadata - example_metadata = { - 'source': source_file, - 'language': language, - 'target': target_file, - 'highlight': example.highlight, - 'hidden': example.hidden, - 'named_steps': example.named_steps, - 'sourceUrl': None # Local examples don't have source URLs - } - - examples_data[example_id][client_name] = example_metadata - logging.info(f"Processed {client_name} example for {example_id}") + # Process each file in local_examples directory and subdirectories + for root, _, files in os.walk(local_examples_dir): + for filename in files: + source_file = os.path.join(root, filename) + + # Get language from file extension + language = get_language_from_extension(filename) + if not language: + logging.warning(f"Unknown file extension for: {filename}") + continue + + # Get example ID from file content + example_id = get_example_id_from_file(source_file) + if not example_id: + logging.warning(f"No EXAMPLE: header found in {filename}") + continue + + logging.info(f"Processing local example: {example_id} ({language}) " + f"from {source_file}") + + # Create target directory + target_dir = os.path.join(examples_dir, example_id) + mkdir_p(target_dir) + + # Initialize example data + if example_id not in examples_data: + examples_data[example_id] = {} + + # Copy file to target directory with local_ prefix + # Include subdirectory structure in the filename to avoid conflicts + relative_path = os.path.relpath(source_file, local_examples_dir) + relative_dir = os.path.dirname(relative_path) + base_name = os.path.splitext(filename)[0] + ext = os.path.splitext(filename)[1] + + # Create a unique filename that includes subdirectory info + if relative_dir and relative_dir != '.': + # Replace path separators with underscores for flat filename + subdir_prefix = relative_dir.replace(os.sep, '_') + target_filename = f"local_{subdir_prefix}_{base_name}{ext}" + else: + target_filename = f"local_{base_name}{ext}" + + target_file = os.path.join(target_dir, target_filename) + shutil.copy2(source_file, target_file) + + # Process with Example class + example = Example(language, target_file) + + # Get client name + client_name = get_client_name_from_language(language) + + # Create metadata + example_metadata = { + 'source': source_file, + 'language': language, + 'target': target_file, + 'highlight': example.highlight, + 'hidden': example.hidden, + 'named_steps': example.named_steps, + 'sourceUrl': None # Local examples don't have source URLs + } + + examples_data[example_id][client_name] = example_metadata + logging.info(f"Processed {client_name} example for {example_id}") # Save updated examples data dump_dict(examples_json, examples_data) @@ -151,8 +159,8 @@ def process_local_examples(local_examples_dir: str = 'local_examples', if __name__ == '__main__': - logging.basicConfig(level=logging.INFO, - format='%(levelname)s: %(message)s') - + logging.basicConfig(level=logging.INFO, + format='%(levelname)s: %(message)s') + process_local_examples() print("Local examples processing complete") diff --git a/content/develop/clients-example-test.md b/content/develop/clients-example-test.md new file mode 100644 index 000000000..c6618adac --- /dev/null +++ b/content/develop/clients-example-test.md @@ -0,0 +1,127 @@ +--- +Title: TCE test +alwaysopen: false +categories: +- docs +- operate +- rs +description: Test for tabbed-clients-example.html +weight: 1 +linkTitle: TCE test +--- + +This page demonstrates the new named parameter syntax for the `clients-example` shortcode while maintaining backward compatibility with positional parameters. + +## Basic Usage with Named Parameters + +### Example 1: Basic named parameters +Using the new named parameter syntax with just the required parameters: + +{{< clients-example set="stream_tutorial" step="xadd" >}} +> XADD race:france * rider Castilla speed 30.2 position 1 location_id 1 +"1692632086370-0" +{{< /clients-example >}} + +### Example 2: Named parameters with language filter +Filtering to show only specific client languages: + +{{< clients-example set="py_home_json" step="query1" lang_filter="Python" >}} +{{< /clients-example >}} + +### Example 3: Named parameters with custom max lines +Limiting the number of lines displayed in the Redis CLI tab: + +{{< clients-example set="hash_tutorial" step="set_get_all" max_lines="2" >}} +> JSON.SET "bicycle:0" "." "{\"brand\": \"Velorim\", \"model\": \"Jigger\", \"price\": 270}" +OK +> JSON.SET "bicycle:1" "." "{\"brand\": \"Bicyk\", \"model\": \"Hillcraft\", \"price\": 1200}" +OK +{{< /clients-example >}} + +### Example 4: Named parameters with custom tab name +Using a custom name for the Redis CLI tab: + +{{< clients-example set="cmds_list" step="llen" dft_tab_name="🔧 Redis Commands" >}} +redis> LPUSH mylist "World" +(integer) 1 +redis> LPUSH mylist "Hello" +(integer) 2 +redis> LLEN mylist +(integer) 2 +{{< /clients-example >}} + +### Example 5: Named parameters with custom footer links +Adding custom footer links to the Redis CLI tab: + +{{< clients-example set="cmds_hash" step="hvals" dft_tab_name="Redis CLI Example" dft_tab_link_title="Learn More" dft_tab_url="https://redis.io/commands/hvals" >}} +redis> HSET myhash field1 "Hello" +(integer) 1 +redis> HSET myhash field2 "World" +(integer) 1 +redis> HVALS myhash +1) "Hello" +2) "World" +{{< /clients-example >}} + +## Backward Compatibility Tests + +### Example 6: Original positional parameters (2 params) +This should work exactly as before: + +{{< clients-example stream_tutorial xrange >}} +> XRANGE race:france 1692632086370-0 + COUNT 2 +{{< /clients-example >}} + +### Example 7: Original positional parameters (4 params) +Testing with language filter and max lines: + +{{< clients-example search_quickstart add_documents "" 3 >}} +> JSON.SET "bicycle:0" "." "{\"brand\": \"Velorim\", \"model\": \"Jigger\", \"price\": 270}" +OK +> JSON.SET "bicycle:1" "." "{\"brand\": \"Bicyk\", \"model\": \"Hillcraft\", \"price\": 1200}" +OK +{{< /clients-example >}} + +## Parameter Reference + +### Named Parameters + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `set` | string | Name of the example set (required) | - | +| `step` | string | Example step name (required) | - | +| `lang_filter` or `language` | string | Language filter to show only specific clients | `""` (all languages) | +| `max_lines` | integer | Maximum number of lines shown in Redis CLI tab | `100` | +| `dft_tab_name` | string | Custom name for the Redis CLI tab | `">_ Redis CLI"` | +| `dft_tab_link_title` | string | Custom footer link title for Redis CLI tab | - | +| `dft_tab_url` | string | Custom footer link URL for Redis CLI tab | - | + +### Positional Parameters (Backward Compatibility) + +| Position | Type | Description | Default | +|----------|------|-------------|---------| +| 0 | string | Name of the example set (required) | - | +| 1 | string | Example step name (required) | - | +| 2 | string | Language filter | `""` | +| 3 | integer | Maximum number of lines | `100` | +| 4 | string | Custom first tab name | `">_ Redis CLI"` | +| 5 | string | Custom first tab footer link title | - | +| 6 | string | Custom first tab footer link URL | - | + +## Migration Guide + +### Before (Positional Parameters) +```hugo +{{}} +{{}} +{{}} +``` + +### After (Named Parameters) +```hugo +{{}} +{{}} +{{}} +``` + +The named parameter syntax is more readable and self-documenting, making it easier to understand what each parameter does without referring to documentation. diff --git a/layouts/partials/tabbed-clients-example.html b/layouts/partials/tabbed-clients-example.html index 5d77838ad..dda5df4a2 100644 --- a/layouts/partials/tabbed-clients-example.html +++ b/layouts/partials/tabbed-clients-example.html @@ -14,7 +14,15 @@ {{ $tabs := slice }} {{/* Render redis-cli example from inner content if any */}} {{ if (ne (trim $redisCommands "\n") "") }} - {{ $redisCliContent := highlight (trim $redisCommands "\n") "plaintext" (printf "linenos=false,hl_lines=1-%d" $redisCommandsLineLimit ) }} + {{ $highlightOptions := "linenos=false" }} + {{ $redisCommandsLineLimitInt := 0 }} + {{ if $redisCommandsLineLimit }} + {{ $redisCommandsLineLimitInt = int $redisCommandsLineLimit }} + {{ end }} + {{ if gt $redisCommandsLineLimitInt 0 }} + {{ $highlightOptions = printf "linenos=false,hl_lines=1-%d" $redisCommandsLineLimitInt }} + {{ end }} + {{ $redisCliContent := highlight (trim $redisCommands "\n") "plaintext" $highlightOptions }} {{ $tabs = $tabs | append (dict "title" "redis-cli" "displayName" $cliTabName "content" $redisCliContent "limit" $redisCommandsLineLimit "customFooterLinkText" $cliFooterLinkText "customFooterLinkUrl" $cliFooterLinkUrl) }} {{ end }} diff --git a/layouts/shortcodes/clients-example.html b/layouts/shortcodes/clients-example.html index a0f199ba8..22203ae0a 100644 --- a/layouts/shortcodes/clients-example.html +++ b/layouts/shortcodes/clients-example.html @@ -1,9 +1,51 @@ -{{ .Scratch.Set "example" (.Get 0) }} -{{ .Scratch.Set "step" (.Get 1) }} -{{ .Scratch.Set "lang" (.Get 2) }} -{{ .Scratch.Set "maxLines" (.Get 3) }} -{{ .Scratch.Set "cli_tab_name" (.Get 4) }} -{{ .Scratch.Set "cli_footer_link_text" (.Get 5) }} -{{ .Scratch.Set "cli_footer_link_url" (.Get 6) }} +{{/* + clients-example shortcode - supports both positional and named parameters + + Named parameters: + - set: Name of the example set (required) + - step: Example step name (required) + - lang_filter: Language filter (optional, default: "") + - max_lines: Maximum number of lines shown by default (optional, default: 100) + - dft_tab_name: Custom first tab name (optional, default: ">_ Redis CLI") + - dft_tab_link_title: Custom first tab footer link title (optional) + - dft_tab_url: Custom first tab footer link URL (optional) + + Positional parameters (for backward compatibility): + - 0: example set name + - 1: step name + - 2: language filter + - 3: max lines + - 4: custom first tab name + - 5: custom first tab footer link title + - 6: custom first tab footer link URL +*/}} + +{{/* Determine if we're using named or positional parameters */}} +{{ $usingNamedParams := false }} +{{ if .Get "set" }} + {{ $usingNamedParams = true }} +{{ end }} + +{{/* Set parameters based on whether we're using named or positional */}} +{{ if $usingNamedParams }} + {{/* Named parameters */}} + {{ .Scratch.Set "example" (.Get "set") }} + {{ .Scratch.Set "step" (.Get "step") }} + {{ .Scratch.Set "lang" (or (.Get "lang_filter") (.Get "language") "") }} + {{ .Scratch.Set "maxLines" (.Get "max_lines") }} + {{ .Scratch.Set "cli_tab_name" (.Get "dft_tab_name") }} + {{ .Scratch.Set "cli_footer_link_text" (.Get "dft_tab_link_title") }} + {{ .Scratch.Set "cli_footer_link_url" (.Get "dft_tab_url") }} +{{ else }} + {{/* Positional parameters (backward compatibility) */}} + {{ .Scratch.Set "example" (.Get 0) }} + {{ .Scratch.Set "step" (.Get 1) }} + {{ .Scratch.Set "lang" (.Get 2) }} + {{ .Scratch.Set "maxLines" (.Get 3) }} + {{ .Scratch.Set "cli_tab_name" (.Get 4) }} + {{ .Scratch.Set "cli_footer_link_text" (.Get 5) }} + {{ .Scratch.Set "cli_footer_link_url" (.Get 6) }} +{{ end }} + {{ .Scratch.Set "redisCommands" .Inner }} {{ partial "tabbed-clients-example.html" . }} diff --git a/local_examples/PipeTransExample.cs b/local_examples/temp/PipeTransExample.cs similarity index 100% rename from local_examples/PipeTransExample.cs rename to local_examples/temp/PipeTransExample.cs diff --git a/local_examples/dt-vec-set.js b/local_examples/temp/dt-vec-set.js similarity index 100% rename from local_examples/dt-vec-set.js rename to local_examples/temp/dt-vec-set.js diff --git a/local_examples/HomeProbDtsExample.java b/local_examples/temp/prob/HomeProbDtsExample.java similarity index 100% rename from local_examples/HomeProbDtsExample.java rename to local_examples/temp/prob/HomeProbDtsExample.java diff --git a/local_examples/HomeProbExample.cs b/local_examples/temp/prob/HomeProbExample.cs similarity index 100% rename from local_examples/HomeProbExample.cs rename to local_examples/temp/prob/HomeProbExample.cs diff --git a/local_examples/home_prob_dts.py b/local_examples/temp/prob/home_prob_dts.py similarity index 100% rename from local_examples/home_prob_dts.py rename to local_examples/temp/prob/home_prob_dts.py diff --git a/local_examples/TimeSeriesTutorial.cs b/local_examples/temp/time_series/TimeSeriesTutorial.cs similarity index 100% rename from local_examples/TimeSeriesTutorial.cs rename to local_examples/temp/time_series/TimeSeriesTutorial.cs diff --git a/local_examples/TimeSeriesTutorialExample.java b/local_examples/temp/time_series/TimeSeriesTutorialExample.java similarity index 100% rename from local_examples/TimeSeriesTutorialExample.java rename to local_examples/temp/time_series/TimeSeriesTutorialExample.java diff --git a/local_examples/dt-time-series.js b/local_examples/temp/time_series/dt-time-series.js similarity index 100% rename from local_examples/dt-time-series.js rename to local_examples/temp/time_series/dt-time-series.js diff --git a/local_examples/dt_time_series.py b/local_examples/temp/time_series/dt_time_series.py similarity index 100% rename from local_examples/dt_time_series.py rename to local_examples/temp/time_series/dt_time_series.py