crate-docs-theme 0.47.1.dev6__tar.gz → 0.49.0__tar.gz

{crate_docs_theme-0.47.1.dev6/src/crate_docs_theme.egg-info → crate_docs_theme-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crate-docs-theme
-Version: 0.47.1.dev6
+Version: 0.49.0
 Summary: CrateDB Documentation Theme
 Home-page: https://github.com/crate/crate-docs-theme
 Author: Crate.IO GmbH
@@ -26,12 +26,12 @@ Requires-Dist: furo==2025.12.19
 Requires-Dist: jinja2<4,>=3
 Requires-Dist: jupysql<0.12
 Requires-Dist: myst-nb<1.4
-Requires-Dist: myst-parser[linkify]<5
+Requires-Dist: myst-parser[linkify]<6
 Requires-Dist: snowballstemmer<4
-Requires-Dist: sphinx<9,>=7.1
+Requires-Dist: sphinx<10,>=7.1
 Requires-Dist: sphinx-basic-ng==1.0.0b2
 Requires-Dist: sphinx-copybutton<1,>=0.3.1
-Requires-Dist: sphinx-design-elements==0.4.1
+Requires-Dist: sphinx-design-elements<0.5
 Requires-Dist: sphinx-inline-tabs
 Requires-Dist: sphinx-sitemap<2.10.0
 Requires-Dist: sphinx-togglebutton<1

{crate_docs_theme-0.47.1.dev6 → crate_docs_theme-0.49.0}/setup.py

@@ -62,12 +62,12 @@ setup(
         "jinja2>=3,<4",
         "jupysql<0.12",
         "myst-nb<1.4",
-        "myst-parser[linkify]<5",
+        "myst-parser[linkify]<6",
         "snowballstemmer<4",
-        "sphinx>=7.1,<9",
+        "sphinx>=7.1,<10",
         "sphinx-basic-ng==1.0.0b2",
         "sphinx-copybutton>=0.3.1,<1",
-        "sphinx-design-elements==0.4.1",
+        "sphinx-design-elements<0.5",
         "sphinx-inline-tabs",
         "sphinx-sitemap<2.10.0",
         "sphinx-togglebutton<1",

{crate_docs_theme-0.47.1.dev6 → crate_docs_theme-0.49.0}/src/crate/theme/rtd/__init__.py

@@ -23,9 +23,9 @@
 
 import os
 
-VERSION = (0, 47, 1)
+VERSION = (0, 49, 0)
 
-__version__ = ".".join(str(v) for v in VERSION) + ".dev6"
+__version__ = ".".join(str(v) for v in VERSION) # + ".dev0"
 __version_full__ = __version__
 
 

{crate_docs_theme-0.47.1.dev6 → crate_docs_theme-0.49.0}/src/crate/theme/rtd/conf/__init__.py

@@ -206,6 +206,35 @@ nb_execution_raise_on_error = True
 
 def setup(app):
 
+    def setup_sphinx_compatibility():
+        """
+        Resolve problem with `sphinx_build_compatibility` extension.
+
+        Add Sphinx extension at runtime, in order to be able to configure it previously.
+        This is needed because it has some quirks that reveal themselves when invoked in
+        non-RTD environments.
+
+        - https://github.com/crate/crate-docs-theme/issues/536
+        - https://about.readthedocs.com/blog/2024/07/addons-by-default/
+        - https://github.com/readthedocs/sphinx-build-compatibility
+        """
+
+        # Extension error (sphinx_build_compatibility.extension):
+        # Handler <function manipulate_config at 0x10a4289a0> for event 'config-inited' threw an exception
+        # (exception: argument of type 'NoneType' is not iterable)
+        os.environ.setdefault("READTHEDOCS_GIT_CLONE_URL", "")
+
+        # IndexError: list index out of range
+        # project_id = response_project["results"][0]["id"]
+        # Currently needs a valid project on PyPI. Long-term fix should go into upstream code.
+        os.environ.setdefault("READTHEDOCS_PROJECT", "crate-docs-theme")
+
+        # Exception: 'NoneType' object is not subscriptable
+        os.environ.setdefault("READTHEDOCS_GIT_COMMIT_HASH", "")
+
+        # Register vendorized Sphinx plugin.
+        app.setup_extension("crate.theme.vendor.rtd_compat.extension")
+
     # Configure Sphinx/RTD to host projects on a custom domain, but also on a non-root resource.
     def configure_self_hosted_on_path(app_inited):
         """
@@ -299,6 +328,9 @@ def setup(app):
         except Exception as ex:
             print(f"ERROR: Unable to adjust `html_context`. Reason: {ex}")
 
+    # Read The Docs compatibility issues.
+    setup_sphinx_compatibility()
+
     # Modern / NG / Furo.
     app.require_sphinx("3.0")
     app.connect("html-page-context", _html_page_context)

crate_docs_theme-0.49.0/src/crate/theme/rtd/crate/directives/stepper.py

@@ -0,0 +1,217 @@
+# -*- coding: utf-8; -*-
+"""
+Stepper directive for step-by-step documentation.
+
+Usage (MyST markdown):
+```
+:::{stepper}
+## First step
+Content for first step.
+
+## Second step
+Content for second step.
+
+### Nested heading
+This stays inside step two.
+:::
+```
+
+Each heading at the first level inside the stepper becomes a numbered step.
+Deeper headings remain as nested content within their parent step.
+"""
+
+import re
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+
+class stepper_node(nodes.General, nodes.Element):
+    """Container node for the stepper component."""
+    pass
+
+
+class step_node(nodes.General, nodes.Element):
+    """Individual step node within a stepper."""
+    pass
+
+
+class step_title_node(nodes.General, nodes.Element):
+    """Step title node that renders as a proper heading element."""
+    pass
+
+
+class StepperDirective(SphinxDirective):
+    """Container for step-by-step instructions.
+
+    Converts MyST markdown headings into numbered steps while preserving
+    their level and anchors for deep linking. Only the first heading level
+    encountered becomes steps; deeper headings stay nested within steps.
+    """
+
+    has_content = True
+    option_spec = {
+        'class': str,
+    }
+
+    def run(self):
+        stepper = stepper_node()
+        stepper['classes'] = self.options.get('class', '').split()
+
+        # Pre-scan content to detect heading levels from MyST markdown
+        # and determine the step level (first heading level found)
+        heading_levels = {}
+        step_level = None
+        for line in self.content:
+            match = re.match(r'^(#{1,6})\s+(.+)$', line.strip())
+            if match:
+                level = len(match.group(1))
+                title = match.group(2).strip()
+                slug = nodes.make_id(title)
+                heading_levels[slug] = level
+                # First heading level becomes the step level
+                if step_level is None:
+                    step_level = level
+
+        # Parse the content
+        container = nodes.container()
+        self.state.nested_parse(self.content, self.content_offset, container)
+
+        step_number = 1
+        current_step = None
+        intro_content = []
+
+        for child in container.children:
+            # MyST parser uses rubric nodes for headings when they appear inside
+            # a directive/container.
+            is_markdown_heading = False
+
+            if isinstance(child, nodes.rubric):
+                # Get heading info
+                heading_id = child.get('ids', [''])[0] if child.get('ids') else ''
+                heading_text = child.astext()
+
+                # Only process as a heading if this rubric corresponds to a
+                # markdown heading (found in pre-scan). Explicit rubric directives
+                # won't be in heading_levels and should be treated as regular content.
+                if heading_id in heading_levels:
+                    is_markdown_heading = True
+                    heading_level = heading_levels[heading_id]
+
+                    # Only treat as new step if at the step level
+                    if heading_level == step_level:
+                        # Close previous step if any
+                        if current_step is not None:
+                            stepper += current_step
+
+                        # Add intro content before first step
+                        if intro_content:
+                            for item in intro_content:
+                                stepper += item
+                            intro_content = []
+
+                        # Create new step
+                        current_step = step_node()
+                        current_step['step-number'] = step_number
+                        current_step['classes'] = ['stepper-step']
+
+                        # Create step title node
+                        title_node = step_title_node()
+                        title_node['ids'] = child.get('ids', [])
+                        title_node['level'] = heading_level
+                        title_node['text'] = heading_text
+                        current_step += title_node
+
+                        step_number += 1
+                    else:
+                        # Nested heading - add as content within current step
+                        if current_step is not None:
+                            # Convert rubric to a proper heading node for nested headings
+                            title_node = step_title_node()
+                            title_node['ids'] = child.get('ids', [])
+                            title_node['level'] = heading_level
+                            title_node['text'] = heading_text
+                            current_step += title_node
+                        else:
+                            intro_content.append(child)
+
+            # Handle regular content (non-heading rubrics and all other nodes)
+            if not is_markdown_heading:
+                if current_step is not None:
+                    current_step += child
+                else:
+                    intro_content.append(child)
+
+        if current_step is not None:
+            stepper += current_step
+
+        if intro_content:
+            for item in intro_content:
+                stepper += item
+
+        return [stepper]
+
+
+# HTML Translator functions
+
+def html_visit_stepper_node(self, node):
+    self.body.append(self.starttag(node, 'div', CLASS='stepper'))
+
+
+def html_depart_stepper_node(self, node):
+    self.body.append('</div>\n')
+
+
+def html_visit_step_node(self, node):
+    step_number = node.get('step-number', '')
+    self.body.append('<div class="stepper-step">\n')
+    self.body.append(f'<div class="stepper-number">{step_number}</div>\n')
+    self.body.append('<div class="stepper-content">\n')
+
+
+def html_depart_step_node(self, node):
+    self.body.append('</div>\n')  # Close stepper-content
+    self.body.append('</div>\n')  # Close stepper-step
+
+
+def html_visit_step_title_node(self, node):
+    level = node.get('level', 3)
+    heading_id = node.get('ids', [''])[0] if node.get('ids') else ''
+    text = node.get('text', '')
+
+    id_attr = f' id="{heading_id}"' if heading_id else ''
+    headerlink = ''
+    if heading_id:
+        headerlink = (
+            f'<a class="headerlink" href="#{heading_id}" '
+            f'title="Link to this heading">¶</a>'
+        )
+    self.body.append(f'<h{level}{id_attr}>{text}{headerlink}</h{level}>\n')
+    raise nodes.SkipNode
+
+
+def html_depart_step_title_node(self, node):
+    pass  # Not called due to SkipNode
+
+
+def setup(app):
+    """Register the stepper directive 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_node(
+        step_title_node,
+        html=(html_visit_step_title_node, html_depart_step_title_node)
+    )
+
+    app.add_directive('stepper', StepperDirective)
+
+    return {
+        'version': '1.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

crate_docs_theme-0.49.0/src/crate/theme/rtd/crate/static/bundle/545e2a01321b20c6484b.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M15.707 12l-5.647-5.646a.5.5 0 01.708-.708l6 6a.5.5 0 010 .708l-6 6a.5.5 0 01-.708-.708L15.707 12z"/></svg>