script rendering docs

docs/prerelease/1.4/_highlights.qmd

@@ -7,4 +7,6 @@ Quarto 1.4 includes the following new features:
 
 -   [Inline Execution for Jupyter](/docs/prerelease/1.4/inline.qmd)---Support for executing inline expressions when using Jupyter kernels. 
 
+-   [Script Rendering for Jupyter](/docs/prerelease/1.4/script.qmd)---Support for rendering script files (e.g. `.py`, `.jl`, or `.r`) that are [specially formatted](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) as notebooks.
+
 -   [Lua changes](/docs/prerelease/1.4/lua_changes.qmd)---Quarto v1.4 adds new features to writers of Lua filters.

docs/prerelease/1.4/script.qmd

@@ -0,0 +1,124 @@
+---
+title: "Script Rendering for Jupyter"
+---
+
+{{< include _pre-release-feature.qmd >}}
+
+## Overview
+
+Quarto v1.4 includes support for rendering script files (e.g. `.py`, `.jl`, or `.r`) that are specially formatted as notebooks. Script rendering makes use of the [percent format](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) that is supported by several other other tools including Spyder, VS Code, PyCharm, and Jupytext.
+
+For example, here is a Python script that includes both markdown and code cells:
+
+``` {.python filename="script.py"}
+# %% [markdown] 
+# ---
+# title: Palmer Penguins
+# author: Norah Jones
+# date: 3/12/23
+# ---
+
+# %% 
+#| echo: false
+import pandas as pd
+df = pd.read_csv("palmer-penguins.csv")
+
+# %% [markdown]
+"""
+## Exploring the data
+
+See @fig-bill-sizes for an exploration of bill sizes by species.
+"""
+
+# %% 
+#| label: fig-bill-sizes
+#| fig-cap: Bill Sizes by Species
+
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+g = sns.FacetGrid(df, hue="species", height=3, aspect=3.5/1.5)
+g.map(plt.scatter, "bill_length_mm", "bill_depth_mm").add_legend()
+```
+
+Code cells are delimited by `# %%` and markdown cells are delimited by `# %% [markdown]`. Markdown content can either be included in single line comments (`#`) or multi-line strings (`"""`), both of which are illustrated above.
+
+Note that cell options are included as normal using `#|` prefixed comments (e.g. `#| echo: false`). Also note that you can include blank lines within cells (cells continue until another cell is encountered).
+
+## Render and Preview
+
+Rendering and previewing notebook scripts works exactly like `.qmd` and `.ipynb` files. For example, the following commands are all valid:
+
+```bash
+$ quarto render script.py
+$ quarto render script.jl
+
+$ quarto preview script.py
+$ quarto preview script.jl
+```
+
+Jupyter scripts rendered with Quarto must begin with a `# %% [markdown]` cell (which normally includes the `title` and other YAML options). This convention is how Quarto knows that it should parse code cells using the percent format (as opposed to other notebook as script formats that may be supported in the future).
+
+Jupyter script rendering is supported for Python, Julia, and R. Note that for R scripts, the [IRkernel](https://irkernel.github.io) will be used to execute code cells rather than Knitr (support for the Knitr [spin](https://bookdown.org/yihui/rmarkdown-cookbook/spin.html) script format is planned but not yet implemented).
+
+The latest version (v1.97.0) of the [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) also implements support for render and preview of Jupyter scripts.
+
+
+## Generating Markdown
+
+Jupyter scripts are especially convenient when most of your document consists of code that dynamically generates markdown. You can write markdown from Python using functions in the `IPython.display` module. For example:
+
+```python
+#| %%
+#| echo: false
+radius = 10
+from IPython.display import display, Markdown
+display(Markdown("The _radius_ of the circle is **{radius}**."
+    .format(radius = radius)))
+```
+
+Note that dynamically generated markdown will still be enclosed in the standard Quarto output divs. If you want to remove all of Quarto's default output enclosures use the `output: asis` option. For example:
+
+```python
+#| %%
+#| echo: false
+#| output: asis
+radius = 10
+from IPython.display import display, Markdown
+display(Markdown("The _radius_ of the circle is **{radius}**."
+    .format(radius = radius)))
+```
+
+
+## Raw Cells
+
+You can include raw cells (e.g. HTML or LaTeX) within scripts using the `# %% [raw]` cell delimiter along with a `format` attribute, for example:
+
+```python
+# %% [raw] format="html"
+"""
+<iframe width="560" height="315" src="https://www.youtube.com/embed/lJIrF4YjHfQ?si=aP7PxA1Pz8IIoQUX"></iframe>
+"""
+```
+
+## Scripts in Projects
+
+Jupyter scripts can also be included within [projects](/docs/projects/quarto-projects.qmd) (e.g. websites, blogs, etc.). Scripts within projects are only rendered by Quarto when they have a markdown cell at the top (e.g. `# %% [markdown]`). 
+
+If for some reason you need to ignore a script that begins with a markdown cell, you can create an explict render list in `_quarto.yml` that excludes individual scripts as required, for example:
+
+```yaml
+project:
+  type: website
+  render:
+    - "*.{qmd,ipynb,py}"
+    - "!utils.py"
+```
+
+Note that this technique is documented for the sake of completeness---in practice you should almost never need to do this since Python scripts rarely begin with `# %% [markdown]` unless you are authoring them specifically as notebooks. 
+
+
+
+
+
+