From 8025dd39962432b4ce92694820c67cd327c2e421 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tun=C3=A7=20Ba=C5=9Far=20K=C3=B6se?= Date: Fri, 20 Sep 2024 10:49:13 +0300 Subject: [PATCH] Add tests and docs --- docs/computation/execute.md | 24 ++++++++++++++ tests/conftest.py | 9 ++++++ tests/notebooks/with_only.md | 24 ++++++++++++++ tests/test_execute.py | 45 ++++++++++++++++++++++++++ tests/test_execute/test_only_html.xml | 16 +++++++++ tests/test_execute/test_only_latex.xml | 16 +++++++++ 6 files changed, 134 insertions(+) create mode 100644 tests/notebooks/with_only.md create mode 100644 tests/test_execute/test_only_html.xml create mode 100644 tests/test_execute/test_only_latex.xml diff --git a/docs/computation/execute.md b/docs/computation/execute.md index 0b280224..4c6e6df1 100644 --- a/docs/computation/execute.md +++ b/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') +``` +```` diff --git a/tests/conftest.py b/tests/conftest.py index 7d8f6436..56477402 100644 --- a/tests/conftest.py +++ b/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] diff --git a/tests/notebooks/with_only.md b/tests/notebooks/with_only.md new file mode 100644 index 00000000..013c3491 --- /dev/null +++ b/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 +``` diff --git a/tests/test_execute.py b/tests/test_execute.py index f39d1df0..df71cb19 100644 --- a/tests/test_execute.py +++ b/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={ diff --git a/tests/test_execute/test_only_html.xml b/tests/test_execute/test_only_html.xml new file mode 100644 index 00000000..73925712 --- /dev/null +++ b/tests/test_execute/test_only_html.xml @@ -0,0 +1,16 @@ + +
+ + 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 diff --git a/tests/test_execute/test_only_latex.xml b/tests/test_execute/test_only_latex.xml new file mode 100644 index 00000000..8279ec51 --- /dev/null +++ b/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