07-12, 13:15–13:45 (US/Pacific), Room 315
To effectively share scientific results, we must blend narrative text and code to create polished, interactive output. Quarto is an open-source scientific publishing system to help you communicate with others through code. Quartodoc is a Python package that generates function references within Quarto websites. Together, these tools create beautiful documentation that is reproducible, accessible, and easily editable.
This talk will include examples of Quarto in action–from simple blogs to expansive Python package documentation including web-assembly powered live examples. Listeners will walk away knowing how to Quarto websites, when to use quartodoc, and how these tools create better documentation.
I’ll be speaking from my experiences as an open source developer who works with multilingual tools, and how Quarto + quartodoc helped to fill those gaps. This talk is intended for anyone who might have to communicate with stakeholders through code using a web-based format. I’ll be focusing on Python package documentation websites, but the stories and examples expose the difficulties in many types of technical communication. The intent is to have a lighthearted talk filled with examples of how to make technical communication and publishing easier and more accessible.
Intro: What is Quarto anyway?
Main body:
1. Why did I choose Quarto?
- I started by building a simple personal blog with Quarto in less than 10 minutes. I loved the experience so much, I wanted to use Quarto for all of the things!
- There is multilingual support for Python, R, Julia, and ObservableJS. In my Quarto blog, I can write content in Jupyter Notebooks, RMarkdown files, or regular Markdown with no add ons or special commands.
- There are options to run my blogs on render– no more worrying if my blog posts have deprecated!
- Demonstrate how to make a personal website in just a few lines of code.
2. Okay, I’m hooked on Quarto. How can I use this tool in other places?
- You can use Quarto for scientific Python package documentation. Specifically, I was working with packages that use R and Python; no tools were filling that gap for me.
- It is possible to build Python documentation with the package quartodoc, which generates API documentation automatically within a Quarto website.
- Demonstrate quartodoc usage with a simple package.
3. Examples of Advanced Quarto usage– it's not just for simple stuff.
- Web Assembly is magical. Giving users the ability to interact with your code without installing anything is a superpower! We will go through examples of Python package documentation built with Quarto that showcases Web Assembly examples.
- I’ll also show highly customized websites to demonstrate the flexibility of Quarto and quartodoc.
4. Conclusion: I love this tool. It has greatly improved my life. I hope it does the same for you!
Isabel Zimmerman is a software engineer at Posit, PBC where she works primarily on building open-source Python tools for MLOps tasks. She also serves as an Editor at pyOpenSci, where she helps facilitate reviewing open scientific software in the Python ecosystem. Outside of computers, Isabel spends most of her time teaching her dogs new tricks or trying to learn how to sew.