diff --git a/.gitignore b/.gitignore index 3cd62aa..991eb68 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,8 @@ !_extensions/*/*/* *.pdf *_files/ +*_site/ +*_book/ /.luarc.json /*.html +*.DS_Store \ No newline at end of file diff --git a/README.md b/README.md index 184647e..20b561b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,13 @@ # Pyodide Extension for Quarto HTML Documents -**We're working on finalizing the Quarto extension. We expect this to be completed shortly.** +**We have an initial version of the extension now available.** This extension enables the [Pyodide](https://pyodide.org/en/stable/) code cell within various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [RevealJS](https://quarto.org/docs/presentations/revealjs/), [Websites](https://quarto.org/docs/websites/), [Blogs](https://quarto.org/docs/websites/website-blog.html), and [Books](https://quarto.org/docs/books). +![`quarto-pyodide` Filter in Action](https://i.imgur.com/gzAyV8H.gif) + +Check out the above example of the extension in action [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/readme)! + ## Installation To use this extension in a [Quarto project](https://quarto.org/docs/projects/quarto-projects.html), install it from within the project's working directory by typing into **Terminal**: @@ -47,6 +51,8 @@ print('Blastoff!') The rendered document can be viewed online [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/readme). +For help setting up other use cases, please see our [Templates](https://quarto.thecoatlessprofessor.com/pyodide/qpyodide-deployment-templates.html) collection. + ## Help To report a bug, please [add an issue](https://github.com/coatless-quarto/pyodide/issues/new) to the repository's [bug tracker](https://github.com/coatless-quarto/pyodide/issues). diff --git a/docs/_quarto.yml b/docs/_quarto.yml index e0e07b8..79753a0 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -28,6 +28,10 @@ website: text: README Example - href: qpyodide-code-cell-demo.qmd text: Pyodide Interactive Cell Demo + - section: "Deployment" + contents: + - href: qpyodide-deployment-templates.qmd + text: Templates - section: "Extra Information" contents: - href: qpyodide-release-notes.qmd diff --git a/docs/qpyodide-deployment-templates.qmd b/docs/qpyodide-deployment-templates.qmd new file mode 100644 index 0000000..7020b3f --- /dev/null +++ b/docs/qpyodide-deployment-templates.qmd @@ -0,0 +1,42 @@ +--- +title: "Deployment Templates" +date: "02-19-2024" +date-modified: last-modified +--- + +Discover a range of sample deployment templates for the `quarto-pyodide` extension at our GitHub repository [here](https://github.com/coatless-quarto/pyodide/tree/main/examples). These templates serve as convenient starting points for various web-based projects that harness the power of the `quarto-pyodide` extension, enabling interactive Python code cells inside of a web browser. Whether you're embarking on an individual report, creating an interactive website, or compiling a digital book, these templates simplify the process, making it effortless to kickstart your own projects. + +# HTML Document Template + +This template is designed for creating standalone HTML documents with interactive Pyodide functionality. It's suitable for individual reports or interactive documents. + +- **Example**: You can find an example of an HTML document template [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/html-document/). +- **Source Code**: Access the source code for this template [here](https://github.com/coatless-quarto/pyodide/tree/main/examples/html-document). + +# RevealJS Presentation Template + +This template is designed for creating standalone RevealJS presentations with interactive Pyodide functionality. It's suitable for creating lecture slides. + +- **Example**: You can find an example of a RevealJS presentation template [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/revealjs/). +- **Source Code**: Access the source code for this template [here](https://github.com/coatless-quarto/pyodide/tree/main/examples/revealjs). + +# Website Template + +This template is meant for building interactive websites with multiple Pyodide-powered pages. It's ideal for websites that have multiple piece of web content that requires interactive data analysis at the "top-level". + +- **Example**: Explore an example of a website template [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/website/). +- **Source Code**: Access the source code for this template [here](https://github.com/coatless-quarto/pyodide/tree/main/examples/website). + +# Blog Template + +For users who want to periodically use Pyodide on their Quarto blog, please use the following template. + +- **Example**: Explore an example of a blog website template [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/blog/). +- **Source Code**: Access the source code for this template [here](https://github.com/coatless-quarto/pyodide/tree/main/examples/blog). + +# Book Template + +The book template is designed for creating interactive web-based books or documentation. It allows you to compile a collection of chapters, sections, and interactive content into a cohesive digital book. + +- **Example**: You can view an example of a book template [here](https://quarto.thecoatlessprofessor.com/pyodide/examples/book). +- **Source Code**: Access the source code for this template [here](https://github.com/coatless-quarto/pyodide/tree/main/examples/book). \ No newline at end of file diff --git a/examples/blog/.gitignore b/examples/blog/.gitignore new file mode 100644 index 0000000..2c8a7a9 --- /dev/null +++ b/examples/blog/.gitignore @@ -0,0 +1,2 @@ +/.quarto/ +/_site/* diff --git a/examples/blog/_extensions b/examples/blog/_extensions new file mode 120000 index 0000000..74119e3 --- /dev/null +++ b/examples/blog/_extensions @@ -0,0 +1 @@ +../../_extensions \ No newline at end of file diff --git a/examples/blog/_quarto.yml b/examples/blog/_quarto.yml new file mode 100644 index 0000000..fdd9761 --- /dev/null +++ b/examples/blog/_quarto.yml @@ -0,0 +1,20 @@ +project: + type: website + +website: + title: "blog" + navbar: + right: + - about.qmd + - icon: github + href: https://github.com/ + - icon: twitter + href: https://twitter.com +format: + html: + theme: cosmo + css: styles.css + +# Enable Pyodide on all post pages +filters: + - pyodide diff --git a/examples/blog/about.qmd b/examples/blog/about.qmd new file mode 100644 index 0000000..bd9c56e --- /dev/null +++ b/examples/blog/about.qmd @@ -0,0 +1,12 @@ +--- +title: "About" +image: profile.jpg +about: + template: jolla + links: + - icon: github + text: GitHub + href: https://github.com/coatless-quarto/pyodide +--- + +This blog is a demo showing how to use the `quarto-pyodide` extension. diff --git a/examples/blog/index.qmd b/examples/blog/index.qmd new file mode 100644 index 0000000..f68f3cf --- /dev/null +++ b/examples/blog/index.qmd @@ -0,0 +1,14 @@ +--- +title: "blog" +listing: + contents: posts + sort: "date desc" + type: default + categories: true + sort-ui: false + filter-ui: false +page-layout: full +title-block-banner: true +--- + + diff --git a/examples/blog/posts/_metadata.yml b/examples/blog/posts/_metadata.yml new file mode 100644 index 0000000..3e9dd01 --- /dev/null +++ b/examples/blog/posts/_metadata.yml @@ -0,0 +1,8 @@ +# options specified here will apply to all posts in this folder + +# freeze computational output +# (see https://quarto.org/docs/projects/code-execution.html#freeze) +freeze: true + +# Enable banner style title blocks +title-block-banner: true diff --git a/examples/blog/posts/embed-slides/image.jpg b/examples/blog/posts/embed-slides/image.jpg new file mode 100644 index 0000000..3ec04c8 Binary files /dev/null and b/examples/blog/posts/embed-slides/image.jpg differ diff --git a/examples/blog/posts/embed-slides/index.qmd b/examples/blog/posts/embed-slides/index.qmd new file mode 100644 index 0000000..b341a90 --- /dev/null +++ b/examples/blog/posts/embed-slides/index.qmd @@ -0,0 +1,45 @@ +--- +title: "Post Containing Slides with Interactive Python Code" +author: "James Balamuta" +date: "2024-02-19" +categories: [news, code, analysis] +image: "image.jpg" +--- + +This is a post that contains slides with interactive code on a [Quarto Blog](https://quarto.org/docs/websites/website-blog.html) through the [`quarto-pyodide`](https://github.com/coatless-quarto/pyodide) extension. The configuration setup for the `quarto-pyodide` extension is taken care of in the `_quarto.yml` file to avoid needing to re-specify options multiple times. + +## Presentation + + + +
+```{=html} + +``` +
+ +## Embed Code + +Place the following code inside of the Quarto Document: + +````html + + +
+```{=html} + +``` +
+```` diff --git a/examples/blog/posts/post-with-code/image.jpg b/examples/blog/posts/post-with-code/image.jpg new file mode 100644 index 0000000..3ec04c8 Binary files /dev/null and b/examples/blog/posts/post-with-code/image.jpg differ diff --git a/examples/blog/posts/post-with-code/index.qmd b/examples/blog/posts/post-with-code/index.qmd new file mode 100644 index 0000000..7144e69 --- /dev/null +++ b/examples/blog/posts/post-with-code/index.qmd @@ -0,0 +1,13 @@ +--- +title: "Post With Interactive Code" +author: "James Balamuta" +date: "2024-03-12" +categories: [news, code, analysis] +image: "image.jpg" +--- + +This is a post with interactive code on a [Quarto Blog](https://quarto.org/docs/websites/website-blog.html) through the [`quarto-pyodide`](https://github.com/coatless-quarto/pyodide) extension. The configuration setup for the `quarto-pyodide` extension is taken care of in the `_quarto.yml` file to avoid needing to re-specify options multiple times. + +```{pyodide-python} +print("Hello {quarto-pyodide} blog world!") +``` diff --git a/examples/blog/profile.jpg b/examples/blog/profile.jpg new file mode 100644 index 0000000..9d50b91 Binary files /dev/null and b/examples/blog/profile.jpg differ diff --git a/examples/blog/styles.css b/examples/blog/styles.css new file mode 100644 index 0000000..2ddf50c --- /dev/null +++ b/examples/blog/styles.css @@ -0,0 +1 @@ +/* css styles */ diff --git a/examples/book/.gitignore b/examples/book/.gitignore new file mode 100644 index 0000000..075b254 --- /dev/null +++ b/examples/book/.gitignore @@ -0,0 +1 @@ +/.quarto/ diff --git a/examples/book/_extensions b/examples/book/_extensions new file mode 120000 index 0000000..a7205cb --- /dev/null +++ b/examples/book/_extensions @@ -0,0 +1 @@ +../../_extensions/ \ No newline at end of file diff --git a/examples/book/_quarto.yml b/examples/book/_quarto.yml new file mode 100644 index 0000000..71e84a0 --- /dev/null +++ b/examples/book/_quarto.yml @@ -0,0 +1,39 @@ +project: + type: book + +book: + title: "Sample quarto-pyodide Book Project" + author: "JJB" + date: today + url: https://quarto.thecoatlessprofessor.com/pyodide/examples/book + repo-url: https://github.com/coatless-quarto/pyodide/tree/main/examples/book + repo-actions: edit + search: true + reader-mode: true + sidebar: + style: "docked" + chapters: + - index.qmd + - part: "Exploring Python" + chapters: + - example-page.qmd + - slide-embed.qmd + - href: ../../ + text: Documentation Portal + page-footer: + left: "An example book with quarto-pyodide." + right: + - icon: github + href: https://github.com/coatless-quarto/pyodide + +# Set the language that should be used for Quarto book +# https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/language +# lang: en + +# Set default options for every webpage that may or may not include Pyodide. +pyodide: + show-startup-message: false # Display status of Pyodide initialization + +# Attach pyodide to every page +filters: + - pyodide diff --git a/examples/book/example-page.qmd b/examples/book/example-page.qmd new file mode 100644 index 0000000..6c5b331 --- /dev/null +++ b/examples/book/example-page.qmd @@ -0,0 +1,44 @@ +--- +title: "Example page" +pyodide: + show-startup-message: true # Display status of Pyodide initialization +--- + +On this page, we set two options directly in the Quarto document. The rest of the options are coming from the `_quarto.yml` project file. These options are considered "global". + +Let's do a quick multi-cell example where we generate data and, then, create a graph. We'll use a modification of the [matplotlib `simple_plot` example](https://matplotlib.org/stable/gallery/lines_bars_and_markers/simple_plot.html). + +First, let's generate some data. +```{pyodide-python} +import numpy as np + +# Data for plotting +t = np.arange(0.0, 2.0, 0.01) +s = 1 + np.sin(2 * np.pi * t) + +# Print t +print(f"Displaying 10 observations of `t`:\n{t[:10]}\n") + +print("Showing the first 10 values of `s`:") +# The last object in the cell does not need print. +s[:10] +``` + +Next, let's retrieve the `t` and `s` variables and create a graph using `matplotlib`. + +```{pyodide-python} +import matplotlib.pyplot as plt + +fig, ax = plt.subplots() +ax.plot(t, s) + +ax.set(xlabel='time (s)', ylabel='voltage (mV)', + title='About as simple as it gets, folks') +ax.grid() + +plt.show() +``` + +:::callout-important +You must include a `plt.show()` call to have the graph be shown. +::: \ No newline at end of file diff --git a/examples/book/index.qmd b/examples/book/index.qmd new file mode 100644 index 0000000..82c11e8 --- /dev/null +++ b/examples/book/index.qmd @@ -0,0 +1,12 @@ +--- +title: "Quarto Pyodide Demo Book" +--- + +# Welcome + +Welcome to a demo Book that uses the [`quarto-pyodide`](https://github.com/coatless/quarto-pyodide) extension to generate interactive code cells with [Quarto](https://quarto.org) and [Pyodide](https://pyodide.org/en/stable/). + +```{pyodide-python} +print("Hello there! Welcome to a {quarto-pyodide} powered book!") +``` + diff --git a/examples/book/slide-embed.qmd b/examples/book/slide-embed.qmd new file mode 100644 index 0000000..373e2fd --- /dev/null +++ b/examples/book/slide-embed.qmd @@ -0,0 +1,47 @@ +--- +title: "Embed Slides" +--- + +On this page, we show how we can embed a RevealJS Presentation inside of a Quarto Book. + +## Presentation + + + +
+```{=html} + + +``` +
+
+```{=html} + +``` +
+ +## Embed Code + +Place the following code inside of the Quarto Document: + +````html + + +
+```{=html} + +``` +
+```` \ No newline at end of file diff --git a/examples/html-document/.gitignore b/examples/html-document/.gitignore new file mode 100644 index 0000000..a20ca82 --- /dev/null +++ b/examples/html-document/.gitignore @@ -0,0 +1,2 @@ +/.quarto/ +/*.html \ No newline at end of file diff --git a/examples/html-document/_extensions b/examples/html-document/_extensions new file mode 120000 index 0000000..a7205cb --- /dev/null +++ b/examples/html-document/_extensions @@ -0,0 +1 @@ +../../_extensions/ \ No newline at end of file diff --git a/examples/html-document/_quarto.yml b/examples/html-document/_quarto.yml new file mode 100644 index 0000000..f5a5b51 --- /dev/null +++ b/examples/html-document/_quarto.yml @@ -0,0 +1,2 @@ +project: + title: "index" diff --git a/examples/html-document/index.qmd b/examples/html-document/index.qmd new file mode 100644 index 0000000..54cbe8a --- /dev/null +++ b/examples/html-document/index.qmd @@ -0,0 +1,16 @@ +--- +title: "quarto-pyodide Demo HTML Document" +format: html +filters: +- pyodide +--- + +# Welcome + +Welcome to a demo HTML Document that uses the [`quarto-pyodide`](https://github.com/coatless-quarto/pyodide) extension to generate interactive code cells with [Quarto](https://quarto.org) and [Pyodide](https://pyodide.org/en/stable/). + +```{pyodide-python} +print("Hello there! Welcome to a quarto-pyodide powered HTML Document!") +``` + +Let's go back to the [documentation portal](../../) diff --git a/examples/website/.gitignore b/examples/website/.gitignore new file mode 100644 index 0000000..2c8a7a9 --- /dev/null +++ b/examples/website/.gitignore @@ -0,0 +1,2 @@ +/.quarto/ +/_site/* diff --git a/examples/website/_extensions b/examples/website/_extensions new file mode 120000 index 0000000..a7205cb --- /dev/null +++ b/examples/website/_extensions @@ -0,0 +1 @@ +../../_extensions/ \ No newline at end of file diff --git a/examples/website/_quarto.yml b/examples/website/_quarto.yml new file mode 100644 index 0000000..eb89745 --- /dev/null +++ b/examples/website/_quarto.yml @@ -0,0 +1,45 @@ +project: + type: website + +website: + title: "Demo Quarto Pyodide Website" + search: true + reader-mode: true + navbar: + left: + - href: index.qmd + text: Home + - href: example-page.qmd + text: Example page + - href: slide-embed.qmd + text: Embed Slides + - href: ../../ + text: Documentation Portal + sidebar: + style: "floating" + contents: + - section: "Content" + contents: + - index.qmd + - example-page.qmd + - slide-embed.qmd + - href: ../../ + text: Documentation Portal + + page-footer: + left: "An example website with quarto-pyodide." + right: + - icon: github + href: https://github.com/coatless-quarto/pyodide + +# Set the language that should be used for Quarto websites +# https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/language +# lang: en + +# Set default options for every webpage that may or may not include Pyodide. +pyodide: + show-startup-message: false # Display status of Pyodide initialization + +# Attach Pyodide to every page +filters: + - pyodide diff --git a/examples/website/example-page.qmd b/examples/website/example-page.qmd new file mode 100644 index 0000000..f0d42f2 --- /dev/null +++ b/examples/website/example-page.qmd @@ -0,0 +1,26 @@ +--- +title: "Example page" +pyodide: + show-startup-message: true # Display status of pyodide initialization +--- + +On this page, we set two options directly in the Quarto document. The rest of the options are coming from the `_quarto.yml` project file. These options are considered "global". + +```{pyodide-python} +import pandas as pd +import numpy as np + +df = pd.DataFrame( + { + "A": 1.0, + "B": pd.Timestamp("20130102"), + "C": pd.Series(1, index=list(range(4)), dtype="float32"), + "D": np.array([3] * 4, dtype="int32"), + "E": pd.Categorical(["test", "train", "test", "train"]), + "F": "foo", + } +) + + +df +``` \ No newline at end of file diff --git a/examples/website/index.qmd b/examples/website/index.qmd new file mode 100644 index 0000000..c4b1ad2 --- /dev/null +++ b/examples/website/index.qmd @@ -0,0 +1,12 @@ +--- +title: "Quarto pyodide Demo Website" +--- + +# Welcome + +Welcome to a demo website that uses the [`quarto-pyodide`](https://github.com/coatless-quarto/pyodide) extension to generate interactive code cells with [Quarto](https://quarto.org) and [Pyodide](https://pyodide.org/en/stable/). + +```{pyodide-python} +print("Hello there! Welcome to a quarto-pyodide powered website!") +``` + diff --git a/examples/website/slide-embed.qmd b/examples/website/slide-embed.qmd new file mode 100644 index 0000000..7cf4fb2 --- /dev/null +++ b/examples/website/slide-embed.qmd @@ -0,0 +1,41 @@ +--- +title: "Embed Slides" +--- + +On this page, we show how we can embed a RevealJS Presentation inside of a Quarto Website. + +## Presentation + + + +
+```{=html} + +``` +
+ +## Embed Code + +Place the following code inside of the Quarto Document: + +````html + + +
+```{=html} + +``` +
+````