Add tests and docs

docs/computation/execute.md

@@ -227,3 +227,27 @@ which produces:
 
 ```{nb-exec-table}
 ```
+
+(execute/builder-dep)=
+## Builder-dependent execution
+
+```{warning}
+This is an experimental feature that is **not** part of the core `MyST` markup specification, and may be removed in the future. Using `:only:` may also not work well with caching and may require deleting previously built files when switching builders.
+```
+
+It may be desirable to execute different code depending on the Sphinx builder being used.
+For example, one may want to have different setup code for plots to be displayed in a website compared to those in a PDF file obtained via LaTeX.
+One can use the `only` option in situations like these, like in the following example:
+
+````md
+```{code-cell}
+:only: html
+import matplotlib.pyplot as plt
+plt.style.use('ggplot')
+```
+
+```{code-cell}
+:only: latex
+plt.style.use('fivethirtyeight')
+```
+````

tests/conftest.py

@@ -104,6 +104,15 @@ def get_html(self, index=0):
             pytest.fail("html not output")
         return bs4.BeautifulSoup(_path.read_text(), "html.parser")
 
+    def get_latex(self, index=0):
+        """Return the built LaTeX file."""
+        # name = self.files[index][0]
+        # not sure why latex output is named python.tex
+        _path = self.app.outdir / "python.tex"  # (name + ".tex")
+        if not _path.exists():
+            pytest.fail("tex not output")
+        return _path.read_text(encoding="utf-8")
+
     def get_nb(self, index=0):
         """Return the output notebook (after any execution)."""
         name = self.files[index][0]

tests/notebooks/with_only.md

@@ -0,0 +1,24 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: '0.8'
+    jupytext_version: 1.4.1+dev
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Test the `:only:` option
+
+```{code-cell}
+:only: html
+1+1
+```
+
+```{code-cell}
+:only: latex
+2+2
+```

tests/test_execute.py

@@ -1,4 +1,5 @@
 """Test sphinx builds which execute notebooks."""
+
 import os
 from pathlib import Path
 
@@ -327,6 +328,50 @@ def test_nb_exec_table(sphinx_run, file_regression):
     assert any("nb_exec_table" in row.text for row in rows)
 
 
+@pytest.mark.sphinx_params(
+    "with_only.md", conf={"nb_execution_mode": "auto"}, buildername="html"
+)
+def test_only_html(sphinx_run, file_regression):
+    """Test that the table gets output into the HTML,
+    including a row for the executed notebook.
+    """
+    sphinx_run.build()
+    # print(sphinx_run.status())
+    assert not sphinx_run.warnings()
+    file_regression.check(
+        sphinx_run.get_doctree().pformat(), extension=".xml", encoding="utf-8"
+    )
+    # print(sphinx_run.get_html())
+    output = sphinx_run.get_html().select("div.output div.highlight pre")
+    assert len(output) == 1  # check that other cell is not present
+    assert "2" in output  # check value to ensure correct cell is present
+
+
+@pytest.mark.sphinx_params(
+    "with_only.md", conf={"nb_execution_mode": "auto"}, buildername="latex"
+)
+def test_only_latex(sphinx_run, file_regression):
+    """Test that the table gets output into the HTML,
+    including a row for the executed notebook.
+    """
+    sphinx_run.build()
+    # print(sphinx_run.status())
+    assert not sphinx_run.warnings()
+    file_regression.check(
+        sphinx_run.get_doctree().pformat(), extension=".xml", encoding="utf-8"
+    )
+    # print(sphinx_run.get_html())
+    output = sphinx_run.get_latex()
+    correct = (
+        r"\begin{sphinxVerbatim}[commandchars=\\\{\}]" "\n4\n" r"\end{sphinxVerbatim}"
+    )
+    assert correct in output  # check value to ensure correct cell is present
+    wrong = (
+        r"\begin{sphinxVerbatim}[commandchars=\\\{\}]" "\n2\n" r"\end{sphinxVerbatim}"
+    )
+    assert wrong not in output  # check value to ensure other cell is not present
+
+
 @pytest.mark.sphinx_params(
     "custom-formats.Rmd",
     conf={

tests/test_execute/test_only_html.xml

@@ -0,0 +1,16 @@
+<document source="with_only">
+    <section ids="test-the-only-option" names="test\ the\ :only:\ option">
+        <title>
+            Test the 
+            <literal>
+                :only:
+             option
+        <container cell_index="1" cell_metadata="{'only': 'html'}" classes="cell" exec_count="1" nb_element="cell_code">
+            <container classes="cell_input" nb_element="cell_code_source">
+                <literal_block language="ipython3" xml:space="preserve">
+                    1+1
+            <container classes="cell_output" nb_element="cell_code_output">
+                <container nb_element="mime_bundle">
+                    <container mime_type="text/plain">
+                        <literal_block classes="output text_plain" language="myst-ansi" xml:space="preserve">
+                            2

tests/test_execute/test_only_latex.xml

@@ -0,0 +1,16 @@
+<document source="with_only">
+    <section ids="test-the-only-option" names="test\ the\ :only:\ option">
+        <title>
+            Test the 
+            <literal>
+                :only:
+             option
+        <container cell_index="1" cell_metadata="{'only': 'latex'}" classes="cell" exec_count="1" nb_element="cell_code">
+            <container classes="cell_input" nb_element="cell_code_source">
+                <literal_block language="ipython3" xml:space="preserve">
+                    2+2
+            <container classes="cell_output" nb_element="cell_code_output">
+                <container nb_element="mime_bundle">
+                    <container mime_type="text/plain">
+                        <literal_block classes="output text_plain" language="myst-ansi" xml:space="preserve">
+                            4