Merge branch 'main' into DOC-5330

Author: cmilesb

assets/css/index.css

@@ -1531,6 +1531,100 @@ a[href*="#no-click"], img[src*="#no-click"] {
   @apply bg-redis-pen-200 font-semibold;
 }
 
+/* Deprecated Command Styles */
+.deprecated-badge {
+  display: inline-flex !important;
+  align-items: center !important;
+  padding: 0.25rem 0.5rem !important;
+  font-size: 0.75rem !important;
+  font-weight: 700 !important;
+  background-color: rgb(220, 255, 30) !important;
+  color: #000000 !important;
+  border-radius: 9999px !important;
+  border: none !important;
+  flex-shrink: 0 !important;
+}
+
+.deprecated-tooltip {
+  position: absolute !important;
+  z-index: 9999 !important;
+  padding: 0.5rem 0.75rem !important;
+  font-size: 0.875rem !important;
+  font-weight: 500 !important;
+  color: white !important;
+  background-color: #111827 !important;
+  border-radius: 0.5rem !important;
+  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06) !important;
+  opacity: 0 !important;
+  visibility: hidden !important;
+  transition: opacity 300ms ease-in-out !important;
+  pointer-events: none !important;
+  white-space: nowrap !important;
+  bottom: calc(100% + 8px) !important;
+  left: 50% !important;
+  transform: translateX(-50%) !important;
+  max-width: 250px !important;
+  white-space: normal !important;
+  word-wrap: break-word !important;
+}
+
+/* Adjust tooltip position when near right edge */
+.deprecated-tooltip-trigger:nth-last-child(-n+2) .deprecated-tooltip,
+.deprecated-tooltip-trigger:last-child .deprecated-tooltip {
+  left: auto !important;
+  right: 0 !important;
+  transform: none !important;
+}
+
+/* Adjust tooltip position when near left edge */
+.deprecated-tooltip-trigger:nth-child(-n+2) .deprecated-tooltip,
+.deprecated-tooltip-trigger:first-child .deprecated-tooltip {
+  left: 0 !important;
+  right: auto !important;
+  transform: none !important;
+}
+
+.deprecated-tooltip::before {
+  content: '' !important;
+  position: absolute !important;
+  top: 100% !important;
+  left: 50% !important;
+  transform: translateX(-50%) !important;
+  width: 0 !important;
+  height: 0 !important;
+  border-left: 5px solid transparent !important;
+  border-right: 5px solid transparent !important;
+  border-top: 5px solid #111827 !important;
+}
+
+.deprecated-tooltip-trigger {
+  position: relative !important;
+  display: inline-flex !important;
+  z-index: 10 !important;
+}
+
+.deprecated-tooltip-trigger:hover .deprecated-tooltip {
+  opacity: 1 !important;
+  visibility: visible !important;
+}
+
+.command-title-deprecated {
+  display: flex !important;
+  align-items: center !important;
+  gap: 0.5rem !important;
+  flex-wrap: nowrap !important;
+}
+
+.command-title-deprecated .truncate {
+  flex: 1 1 0% !important;
+  min-width: 0 !important;
+}
+
+/* Fix alignment on individual command pages */
+.prose h1.command-name .command-title-deprecated {
+  align-items: center !important;
+}
+
 /* Utility Classes */
 .agent-builder-hidden {
   display: none !important;

build/components/component.py

@@ -273,6 +273,11 @@ def _copy_examples(self):
                 example_metadata['sourceUrl'] = (
                     f'{ex["git_uri"]}/tree/{default_branch}/{ex["path"]}/{os.path.basename(f)}'
                 )
+
+                # Add binderId only if it exists
+                if e.binder_id:
+                    example_metadata['binderId'] = e.binder_id
+
                 examples = self._root._examples
                 if example_id not in examples:
                     examples[example_id] = {}

build/components/example.py

@@ -8,6 +8,7 @@
 STEP_START = 'STEP_START'
 STEP_END = 'STEP_END'
 EXAMPLE = 'EXAMPLE:'
+BINDER_ID = 'BINDER_ID'
 GO_OUTPUT = 'Output:'
 TEST_MARKER = {
     'java': '@Test',
@@ -45,6 +46,7 @@ class Example(object):
     hidden = None
     highlight = None
     named_steps = None
+    binder_id = None
 
     def __init__(self, language: str, path: str) -> None:
         logging.debug("ENTERING: ")
@@ -59,6 +61,7 @@ def __init__(self, language: str, path: str) -> None:
         self.hidden = []
         self.highlight = []
         self.named_steps = {}
+        self.binder_id = None
         self.make_ranges()
         self.persist(self.path)
         logging.debug("EXITING: ")
@@ -88,6 +91,7 @@ def make_ranges(self) -> None:
         rstart = re.compile(f'{PREFIXES[self.language]}\\s?{REMOVE_START}')
         rend = re.compile(f'{PREFIXES[self.language]}\\s?{REMOVE_END}')
         exid = re.compile(f'{PREFIXES[self.language]}\\s?{EXAMPLE}')
+        binder = re.compile(f'{PREFIXES[self.language]}\\s?{BINDER_ID}\\s+([a-zA-Z0-9_-]+)')
         go_output = re.compile(f'{PREFIXES[self.language]}\\s?{GO_OUTPUT}')
         go_comment = re.compile(f'{PREFIXES[self.language]}')
         test_marker = re.compile(f'{TEST_MARKER.get(self.language)}')
@@ -150,6 +154,13 @@ def make_ranges(self) -> None:
             elif re.search(exid, l):
                 output = False
                 pass
+            elif re.search(binder, l):
+                # Extract BINDER_ID hash value
+                match = re.search(binder, l)
+                if match:
+                    self.binder_id = match.group(1)
+                    logging.debug(f'Found BINDER_ID: {self.binder_id} in {self.path}:L{curr+1}')
+                output = False
             elif self.language == "go" and re.search(go_output, l):
                 if output:
                     logging.error("Nested Go Output anchor in {self.path}:L{curr+1} - aborting.")

build/jupyterize/QUICKSTART.md

@@ -0,0 +1,94 @@
+# Jupyterize - Quick Start Guide
+
+## Installation
+
+```bash
+pip install nbformat
+```
+
+## Basic Usage
+
+```bash
+# Convert a file (creates example.ipynb)
+python build/jupyterize/jupyterize.py example.py
+
+# Specify output location
+python build/jupyterize/jupyterize.py example.py -o notebooks/example.ipynb
+
+# Enable verbose logging
+python build/jupyterize/jupyterize.py example.py -v
+```
+
+## What It Does
+
+Converts code example files → Jupyter notebooks (`.ipynb`)
+
+**Automatic:**
+- ✅ Detects language from file extension
+- ✅ Selects appropriate Jupyter kernel
+- ✅ Excludes `EXAMPLE:` and `BINDER_ID` markers
+- ✅ Includes code in `HIDE_START`/`HIDE_END` blocks
+- ✅ Excludes code in `REMOVE_START`/`REMOVE_END` blocks
+- ✅ Creates separate cells for each `STEP_START`/`STEP_END` block
+
+## Supported Languages
+
+| Extension | Language   | Kernel       |
+|-----------|------------|--------------|
+| `.py`     | Python     | python3      |
+| `.js`     | JavaScript | javascript   |
+| `.go`     | Go         | gophernotes  |
+| `.cs`     | C#         | csharp       |
+| `.java`   | Java       | java         |
+| `.php`    | PHP        | php          |
+| `.rs`     | Rust       | rust         |
+
+## Input File Format
+
+```python
+# EXAMPLE: example_id
+# BINDER_ID optional-binder-id
+import redis
+
+# STEP_START connect
+r = redis.Redis()
+# STEP_END
+
+# STEP_START set_get
+r.set('foo', 'bar')
+r.get('foo')
+# STEP_END
+```
+
+## Output Structure
+
+Creates a Jupyter notebook with:
+- **Preamble cell** - Code before first `STEP_START`
+- **Step cells** - Each `STEP_START`/`STEP_END` block
+- **Kernel metadata** - Automatically set based on language
+- **Step metadata** - Step names stored in cell metadata
+
+## Common Issues
+
+**"Unsupported file extension"**
+→ Use a supported extension (.py, .js, .go, .cs, .java, .php, .rs)
+
+**"File must start with EXAMPLE: marker"**
+→ Add `# EXAMPLE: <id>` (or `//` for JS/Go/etc.) as first line
+
+**"Input file not found"**
+→ Check file path is correct
+
+## Testing
+
+```bash
+# Run automated tests
+python build/jupyterize/test_jupyterize.py
+```
+
+## More Information
+
+- **User Guide**: `build/jupyterize/README.md`
+- **Technical Spec**: `build/jupyterize/SPECIFICATION.md`
+- **Implementation**: `build/jupyterize/IMPLEMENTATION.md`
+