Add Stepper directive (#658)

Author: bmunkholm

docs/build.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 1,
   "label": "docs build",
-  "message": "2.1.2"
+  "message": "2.1.5"
 }

docs/myst/stepper.md

@@ -0,0 +1,15 @@
+# Stepper
+
+::::{stepper}
+:::{step} First step
+You can add any content in a step.
+:::
+
+:::{step} Next step
+Some step details
+:::
+
+:::{step} Last step
+Last step details
+:::
+::::

src/crate/theme/rtd/conf/__init__.py

@@ -338,6 +338,10 @@ def apply_html_context_custom(app_inited):
     app.connect("builder-inited", set_proxied_static_path)
     app.connect("builder-inited", apply_html_context_custom)
 
+    # Register stepper directive
+    from crate.theme.rtd.crate.directives import stepper
+    stepper.setup(app)
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,

src/crate/theme/rtd/crate/directives/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8; -*-
+# Directives for crate-docs-theme

src/crate/theme/rtd/crate/directives/stepper.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8; -*-
+"""
+Stepper directive for step-by-step documentation.
+"""
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+
+# Define custom nodes
+class stepper_node(nodes.General, nodes.Element):
+    pass
+
+class step_node(nodes.General, nodes.Element):
+    pass
+
+class StepperDirective(SphinxDirective):
+    """Container for step-by-step instructions."""
+
+    has_content = True
+    option_spec = {
+        'class': str, # directives.class_option is for multiple classes
+    }
+
+    def run(self):
+        stepper = stepper_node()
+        stepper['classes'] = self.options.get('class', '').split() # Add custom classes if provided
+        self_content = nodes.paragraph()
+        self.state.nested_parse(self.content, self.content_offset, self_content)
+
+        step_number = 1
+        for child in self_content.children:
+            if isinstance(child, step_node):
+                child['step-number'] = step_number
+                step_number += 1
+            stepper += child # Add all children from self_content to stepper
+
+        return [stepper]
+
+
+class StepDirective(SphinxDirective):
+    """Individual step in a stepper."""
+
+    has_content = True
+    required_arguments = 1  # Step title
+    optional_arguments = 0
+    final_argument_whitespace = True  # Allow spaces in title
+    option_spec = {
+        'class': str,
+    }
+
+    def run(self):
+        step = step_node()
+        step['classes'] = ['stepper-step']
+        step['classes'].extend(self.options.get('class', '').split())
+
+        # Set title
+        step['step-title'] = self.arguments[0]
+
+        # Parse content
+        self.state.nested_parse(
+            self.content,
+            self.content_offset,
+            step
+        )
+        return [step]
+
+# HTML Translator functions
+def html_visit_stepper_node(self, node):
+    self.context.append('')
+    self.body.append(self.starttag(node, 'div', CLASS='stepper'))
+
+def html_depart_stepper_node(self, node):
+    self.body.append('</div>\n')
+    self.context.pop()
+
+def html_visit_step_node(self, node):
+    self.context.append('')
+    self.body.append(self.starttag(node, 'div', CLASS='stepper-step'))
+    self.body.append(f'<div class="stepper-header">')
+    self.body.append(f'<div class="stepper-number">{node.get("step-number", "")}</div>')
+    self.body.append(f'<div class="stepper-title">{node.get("step-title", "")}</div>')
+    self.body.append(f'</div>')
+    self.body.append(f'<div class="stepper-content">')
+
+def html_depart_step_node(self, node):
+    self.body.append('</div>\n') # Close stepper-content
+    self.body.append('</div>\n') # Close stepper-step
+    self.context.pop()
+
+
+def setup(app):
+    """Register the stepper directives and nodes."""
+    app.add_node(stepper_node, html=(html_visit_stepper_node, html_depart_stepper_node))
+    app.add_node(step_node, html=(html_visit_step_node, html_depart_step_node))
+
+    app.add_directive('stepper', StepperDirective)
+    app.add_directive('step', StepDirective)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

src/crate/theme/rtd/crate/static/css/index.css

@@ -3,3 +3,4 @@
 @import "ng/index.scss";
 @import "crateio-rtd.css";
 @import "custom.css";
+@import "stepper.css";

src/crate/theme/rtd/crate/static/css/stepper.css

@@ -0,0 +1,78 @@
+/* Stepper component styling */
+
+:root {
+  --stepper-number-bg: var(--primary-color);
+  --stepper-number-color: #ffffff;
+  --stepper-line-color: #dee2e6;
+  --stepper-spacing: 2rem;
+  --stepper-number-size: 2rem;
+}
+
+html[data-theme="dark"] {
+  --stepper-line-color: #495057;
+}
+
+.stepper {
+  margin: 2rem 0;
+}
+
+.stepper-step {
+  position: relative;
+  padding-left: 3rem; /* Space for number + line */
+  padding-bottom: var(--stepper-spacing);
+}
+
+.stepper-step:last-child {
+  padding-bottom: 0;
+}
+
+/* Number badge */
+.stepper-number {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: var(--stepper-number-size);
+  height: var(--stepper-number-size);
+  border-radius: 50%;
+  background-color: var(--stepper-number-bg);
+  color: var(--stepper-number-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 600;
+  font-size: 0.9rem;
+  z-index: 2;
+}
+
+/* Connecting line */
+.stepper-step:not(:last-child)::before {
+  content: '';
+  position: absolute;
+  left: calc(var(--stepper-number-size) / 2 - 1px);
+  top: var(--stepper-number-size);
+  bottom: 0;
+  width: 2px;
+  background-color: var(--stepper-line-color);
+  z-index: 1;
+}
+
+/* Header (number + title on same line) */
+.stepper-header {
+  display: flex;
+  align-items: center;
+  margin-bottom: 0.75rem;
+}
+
+.stepper-title {
+  font-weight: 600;
+  font-size: 1.1rem;
+}
+
+/* Content */
+.stepper-content > *:first-child {
+  margin-top: 0;
+}
+
+.stepper-content > *:last-child {
+  margin-bottom: 0;
+}