vortex-data
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/ci.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/conf.py‎
Lines changed: 54 additions & 1 deletion b/‎docs/conf.py‎
Lines changed: 54 additions & 1 deletion
@@ -133,7 +133,7 @@ jobs:
         run: |
           RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
           # nextest doesn't support doc tests, so we run it here
-          cargo test --doc --workspace --all-features --exclude vortex-cxx --exclude vortex-python --exclude vortex-jni --exclude vortex-ffi --exclude xtask --no-fail-fast
+          cargo test --doc --workspace --all-features --exclude vortex-cxx --exclude vortex-jni --exclude vortex-ffi --exclude xtask --no-fail-fast
 
   build-rust:
     name: "Rust build (${{matrix.config.name}})"
 
@@ -52,7 +52,7 @@
 nitpicky = True  # ensures all :class:, :obj:, etc. links are valid
 nitpick_ignore = []
 
-doctest_global_setup = "import pyarrow; import vortex"
+doctest_global_setup = "import pyarrow; import vortex; import vortex as vx"
 doctest_default_flags = (
     doctest.ELLIPSIS | doctest.IGNORE_EXCEPTION_DETAIL | doctest.DONT_ACCEPT_TRUE_FOR_1 | doctest.NORMALIZE_WHITESPACE
 )
@@ -196,6 +196,59 @@ def _post_process(app, builder):
 os.environ["POLARS_TABLE_WIDTH"] = "80"
 
 
+def _convert_python_fenced_blocks_from_rust_to_valid_reST_blocks(app, what, name, obj, options, lines):
+    """Remove Markdown-style code fences from Python docs written in Rust.
+
+    We would like `cargo test` to Just Work (TM). Unfortunately, by default, it executes any
+    code-block in any docstring even though we intend those docs to be *Python* doc tests.
+
+    For example, the following is interpreted by Rust as Rust code (which it will try to doctest):
+
+        /// >>> 1 + 1
+        /// 3
+        fn foo() {
+        }
+
+    What syntax can we use to communicate to Rust "This is not Rust code" but communicate to Python
+    "This is Python code"? The following appears as executable code to both, so it does not work:
+
+        /// .. code-block:: python
+        ///
+        ///     >>> 1 + 1
+        ///     3
+        fn foo() {
+        }
+
+    This does not appear to work unless we wrap all the code in braces or a function, which makes it
+    not valid Python:
+
+        /// #[no_run]
+        /// >>> 1 + 1
+        /// 3
+
+    The following is executed by neither language and does not render properly (because it is not
+    valid reStructured Text):
+
+        /// ```python
+        /// >>> 1 + 1
+        /// 3
+        /// ```
+
+    Okay, so, our solution is to just adopt the last option and explicitly remove the code fences
+    when we parse docstrings in Sphinx.
+
+    """
+    in_block = False
+    for i, line in enumerate(lines):
+        if line == "```python":
+            lines[i] = ""
+            in_block = True
+        elif in_block and line == "```":
+            lines[i] = ""
+            in_block = False
+
+
 def setup(app):
     app.connect("hawkmoth-process-docstring", _replace_rust_references)
     app.connect("write-started", _post_process)
+    app.connect("autodoc-process-docstring", _convert_python_fenced_blocks_from_rust_to_valid_reST_blocks)