Great Docs

0:00

01:07:00

Links Episode Deep Dive Transcript

Panelists

Your documentation has two audiences now - humans reading the rendered HTML, and AI agents trying to make sense of your library. Rich Iannone and Michael Chow from Posit are back on Talk Python with a brand new Python documentation tool called Great Docs that takes both seriously. Rich is the creator of Great Tables, and before that the R package GT, the man has a serious eye for design, and he's pointed that energy at the Python docs ecosystem. We'll talk about how Great Docs spins up a polished site in three commands, why every page ships as Markdown for your favorite LLM, how it leans on Quarto for executable code blocks and tabbed install sections, and where it lands against Sphinx, MkDocs, and Zensical. Plus, you'll meet Tablin. Here we go.

Play on YouTube

Watch the live stream version

Episode Deep Dive

Guests Introduction and Background

Rich Iannone is a software engineer at Posit (PBC) with a long open source track record in the R world before pivoting to Python over the last few years. He is best known as the creator of the R package GT, which he ported to Python as Great Tables, and now as the author of Great Docs, the documentation tool at the center of this episode. Rich has a distinctive eye for design and authorship, and he tends to obsess over the small details (mascots, filter bars, Markdown export buttons) that turn an okay tool into a delightful one.

Michael Chow is also a software engineer on the Posit open source team, where he has spent about four years working full-time on Python tooling. He is the author of QuartoDoc, an earlier API reference generator that sits closer to the bare metal of Quarto, and is used by projects like Ibis. Michael has done a deep dive into the history of Python docs tooling, and he plays an interesting "engineer with style sensibilities" foil to Rich's "wild card" energy on this project.

What to Know If You're New to Python

This episode lives in the intersection of Python packaging, documentation tooling, and the new world of AI-readable docs. A little background on how Python projects expose their APIs and how doc sites typically get built will help most of the discussion click.

Docstrings and API reference: Python lets you attach a string just under a function, class, or module to describe how it works. Doc generators read these "docstrings" and turn them into a browsable API reference. Great Docs builds this section automatically when you point it at a package.
Static site generators: A static site generator turns source files (usually Markdown) into plain HTML, CSS, and JS that any web host can serve. Sphinx, MkDocs, Hugo, Quarto, and Great Docs all output static sites, so they can be deployed to GitHub Pages, Netlify, Vercel, or your own NGINX server with no application runtime needed.
Markdown vs reStructuredText: Markdown is the lightweight syntax most developers know. reStructuredText (RST) is the older, more rigid format Sphinx historically used. Great Docs leans on Markdown so both humans and LLMs can read pages easily, while older tools like Sphinx still center on RST.
LLM-friendly docs: Modern docs need to serve agents like Claude Code and Codex as well as humans. That means shipping a clean Markdown version of every page, an llms.txt index, and clear CLI examples so an AI can read your library quickly and accurately.
Quarto and computational documents: Quarto is Posit's open source publishing system. It treats Markdown files as documents with executable code cells, so the code in your docs actually runs at build time and its output appears beside it. Great Docs uses Quarto as its rendering engine under the hood.

Key Points and Takeaways

Great Docs is a new Python documentation tool that ships polished sites in three commands

Great Docs is Rich Iannone's brand new project that aims to fill a "pkgdown-sized hole" in the Python docs ecosystem. The promise is that you can point it at a Python package, run great-docs init, great-docs build, and great-docs preview, and immediately get a serviceable site with an auto-generated API reference, a user guide, and a config file you can grow into. It is opinionated by design, with Rich's sense of style baked in, so you get something good-looking by default and can customize from there. Rich tested it against many different package layouts so introspection works across a wide range of packaging conventions. The whole tool is built on top of Quarto, but Quarto is held back as an implementation detail rather than something you have to learn first.

Documentation now has two audiences: humans and AI agents

A central theme of the conversation is that every doc site today serves both a human reader and an LLM trying to make sense of your library. Great Docs leans hard into this by shipping a Markdown copy of every page, exposing a "view as Markdown" button, supporting .md URLs, generating an llms.txt index, and including an llms-full.txt that mashes the entire docs into a single file for context loading. Michael Kennedy points out he added similar features to talkpython.fm so Claude Code, Codex, and other agents could navigate the 7.5 million words of podcast content. Rich frames this bluntly: the goal is to make the docs nice for humans but also genuinely consumable by LLMs and agents.

llmstxt.org

Sphinx is the original Python doc site builder, with deep history and real friction

Michael Chow walks through the historical context where Python's own docs reportedly moved from LaTeX to Sphinx, which then powered API docs for huge projects like Pandas and Polars. Sphinx has been a "zero to one" leap for the ecosystem, and the term "how-to" itself migrated into Python docs from the Linux documentation tradition. The friction point today is reStructuredText, which most newer open source developers no longer reach for. Seeing an .rst file is described as a rite of passage that brings "a little tear" to Michael Kennedy's eye. Great Docs is part of a generational shift toward Markdown-first authoring.

The landscape: MkDocs, Zensical, Mintlify, Hugo, and Quarto each occupy different corners

The group surveys the neighbors. MkDocs is the popular Markdown-based alternative to Sphinx, often used with the Material theme. Zensical (covered in an earlier episode with Martin Donath) is a more modern offering that is compatible with Material for MkDocs but aims toward general purpose knowledge bases. Mintlify spans documentation across many languages but stretches toward general-purpose marketing sites too. Hugo and Ghost are general static site generators where you can jam your docs in if you do not need API reference automation. Quarto, made by Posit, handles sites, documents, books, and presentations with executable code cells across R, Python, Julia, and more.

Quarto is the executable foundation underneath Great Docs

Quarto is an open source publishing system from Posit that supports computational notebooks, where Markdown files can contain code cells with engines for R, Python, Julia, and others. At build time, those cells execute and their outputs (tables, plots, results) are embedded into the rendered page. This is what made the Great Tables docs so powerful: a code snippet and the actual generated table appear together without a copy-paste step. Quarto also ships features like tab sets for multi-OS install instructions, citations, cross-references, and a deep extension system. Great Docs uses Quarto extensively but tries to hide it so authors do not have to learn Quarto first.

quarto.org

The "freeze" feature solves the live-data and slow-benchmark problem

Because Quarto runs code at build time, you can hit awkward edge cases: maybe the code touches a live API whose results change, maybe it accesses keys only present on your personal machine, or maybe a benchmark takes too long to rerun on CI. Quarto's freeze mechanism caches the outputs so you can rebuild the site without re-executing the code. Michael Chow notes Great Tables uses freeze for its growing log of blog posts so they do not have to be regenerated every release. Rich confirmed Great Docs works around the ephemeral nature of the build directory so freeze still works cleanly even when you treat outputs as disposable.

quarto.org

Versioned docs, tab sets, and the little touches that show Rich's design eye

Great Docs ships with a long list of "I would never have thought of that" details that elevate it above bare bones API generators. There is a live filter bar on the API reference page that filters items as you type. There is a dedicated section for CLI documentation, reflecting that AI agents like Claude Code now love command line interfaces. There is a Markdown copy button at the top of every page. There is a version selector driven by git tags so you can publish docs for v0.1 alongside the current release, and the older versions actually show the smaller API surface they had at the time. Tab sets let you cleanly show "Mac / Linux / Windows" install instructions inside a single page region.

github.com/posit-dev/great-tables

Rich's design DNA comes from Great Tables, and ultimately from Tufte and a 1949 census manual

Michael Chow describes Rich as Posit's "wild card" with a freaky sense of style, and the Great Tables work is the proof. Great Tables broke a table into named components like header, stub, stub head, spanners, and source notes, and many of those names were lifted from a 1949 US Census manual on tabular presentation that Rich found scanned as a PDF on the web. The same Tufte-flavored "just the right amount of ink" instinct shows up in Great Docs, where Rich obsesses over things like search-as-you-type and clean Markdown export. Sparklines, the Tufte invention of tiny in-cell trend lines, show up here too as the canonical example of compressing meaning into the smallest possible space.

edwardtufte.com

Get-started workflow is intentionally tiny: init, build, preview, watch

Rich walks through the quick start: install Great Docs and Quarto, then run great-docs init to generate a great-docs.yaml config tuned to your package layout. Then great-docs build produces a great-docs/ directory containing the rendered site, and great-docs preview spins up a local web server with your default browser pointed at it. For iterative authoring there is great-docs build --watch, which behaves like the Hugo workflow: edit a Markdown file and the site rebuilds quickly. Once you are happy you wire it into CI and start customizing the config or adding folders like a "recipes" section that appear in the top nav.

github.com/posit-dev/great-tables

Skills and MCP-aware docs point at where the agentic ecosystem is heading

Rich is leaning into agentic AI as a first-class audience. Great Docs has a great-docs skill install workflow that lets library authors publish Claude Code-style skills and lets users browse and install them right from the docs site. The roadmap also includes documenting MCP servers, which do not have function-by-function structure like a normal Python library, so they need a different presentation that covers tools, prompts, and the JSON shape of the protocol. Rich described this as trying to be "a little bit ahead" of where docs are going. The result is a doc tool that treats agents pointing at your site as a real workflow, not an afterthought.

llmstxt.org

Open source sustainability at Posit comes from boring enterprise tools

Asked how Posit pays for a team of dozens of full-time open source engineers, Michael Chow's favorite answer is "a bunch of boring enterprise tools." Posit Connect and Posit Teams solve unglamorous but very real problems for organizations: how to host Jupyter notebooks, RStudio sessions, and scheduled reports for data teams that may not have a dedicated DevOps function. Those products fund the maintainers, who then can stay with projects like Great Tables and Quarto for years, giving them real long-term stability. Rich points out he has been working on this lineage of tools since 2017 when GT first started in R, which adds real credibility that the projects will not be abandoned.

posit.co

Doc tooling is a small collaborative ecosystem, not a winner-takes-all war

Michael Chow specifically calls out Timothée Mazzucotelli (GitHub handle pawamoy), the maintainer of upstream tools like Griffe and mkdocstrings, as a great example of cross-project collaboration. Posit's tools and others all depend on the same upstream parsers and introspection libraries, and the maintainers contribute PRs to each other's projects. They may technically compete at the surface level, but they share infrastructure under the hood. The takeaway for users: when you adopt one of these tools, you are joining a small community of passionate maintainers who actually talk to each other at PyCon.

Deployment is dead simple: it is just static files

Because the output is a self-contained site directory, you can host Great Docs anywhere that serves static files. Rich provides hints for GitHub Pages, Netlify, Vercel, and similar services in the docs. Michael Kennedy shares that he runs his static sites on a regular server with NGINX because, surprisingly, that has been more reliable for him than some cloud hosts. The bigger point: keeping the deployment story boring (a site folder plus a static host) avoids the cascading failures that come with stacks of interdependent services.

Interesting Quotes and Stories

"It feels like a bizarro situation. I know what I could be doing, what I should be doing, theoretically. But things just don't jive sometimes." -- Rich Iannone, on switching from R to Python

"Rich just has this crazy, freaky sense of style. People at Posit just never know what Rich is going to pull out. He's our wild card." -- Michael Chow

"Naming things is so important, otherwise you're just awkwardly describing something over and over again. Like that cell to the top left or these cells off to the side. And eventually you just have to give it a name, even if it's not the best name. These are actually names I stole from a census manual on tables, I think written in 1949." -- Rich Iannone

"If I see an RST file, it's just a little tear wells up in my eye. I'm like, oh gosh, here we go." -- Michael Kennedy

"I have a lot of bizarre experience looking at the history of Python docs." -- Michael Chow

"It's basically just nicing up the docs and making them good for humans, but also consumable by LLMs or agents and such." -- Rich Iannone

"How does Posit pay the bills for people to work on open source? My favorite thing to say is we have a bunch of boring enterprise tools. And no shade on Posit, I actually think that this is the best case scenario." -- Michael Chow

The Tablin origin story is a small gem of the episode. Two years ago while preparing a PyCon talk, Michael Chow noticed a little anthropomorphized spreadsheet character had appeared in the slide deck, popping out from the side of a table to cheer the reader on. "Who's this spreadsheet with eyes and a mouth cheering people on?" Rich's answer was deadpan: "It's Tablin, of course." Tablin is now positioned as a sort of Clippy descendant, "much cooler because he's a table" and shows up just to help and then disappear.

Key Definitions and Terms

Great Docs: A new Python documentation tool from Rich Iannone at Posit that generates polished doc sites with an auto-built API reference, user guide, version selector, and LLM-friendly Markdown exports from a single config file.
Great Tables: Rich's earlier Python library for composing publication-quality display tables from data frames, with support for titles, subtitles, spanners, stub heads, source notes, and formatted cells.
GT: The original R package by Rich that became the design template for Great Tables. Active since 2017.
Quarto: Posit's open source publishing system. Renders Markdown documents, books, sites, and presentations with executable code cells across multiple languages.
QuartoDoc: A separate, more bare-bones API reference generator for Quarto built by Michael Chow, used by projects like Ibis.
pkgdown: The R-ecosystem doc generator that inspired the "point it at your package and get something serviceable" ethos of Great Docs.
Sphinx: The original dominant Python doc site builder. Powers python.org, Pandas, and Polars docs, traditionally written in reStructuredText.
reStructuredText (RST): The older lightweight markup language used by Sphinx, less popular with newer open source developers than Markdown.
MkDocs: A Markdown-based Python documentation site generator, frequently paired with the Material for MkDocs theme.
Material for MkDocs: The popular themed framework on top of MkDocs that Zensical aims to be compatible with.
Zensical: A modern, scalable technical writing platform compatible with Material for MkDocs, heading toward general-purpose knowledge bases.
Mintlify: A general-purpose documentation platform that supports many languages but extends beyond pure docs.
mkdocstrings: Upstream tool maintained by pawamoy that pulls Python docstrings into MkDocs sites.
Griffe: Upstream Python static analysis library, also maintained by pawamoy, that powers introspection in QuartoDoc, Great Docs, and other tools.
llms.txt: A proposed standard, originated by Jeremy Howard, for an LLM-readable Markdown index of a website, analogous to robots.txt and sitemap.xml but aimed at AI agents.
llms-full.txt: A companion to llms.txt that concatenates a project's complete docs into a single Markdown file LLMs can ingest in one go.
Freeze: A Quarto mechanism that caches the outputs of computational cells so you do not re-execute code on every build.
Tab sets: A Quarto authoring primitive for tabbed UI within a single content area (e.g. Mac / Linux / Windows install instructions).
Sparkline: A small, in-line trend line with no axis labels, popularized by Edward Tufte, used in table cells to show direction at a glance.
Posit Connect / Posit Teams: Posit's enterprise products for hosting reports, notebooks, and editor environments, which fund the company's open source work.
MCP server: A Model Context Protocol server that exposes tools, prompts, and resources to AI agents. Documenting these is on the Great Docs roadmap because their shape differs from a normal Python API.
Skills: Reusable, installable agent capabilities (in the Claude Code sense) that Great Docs can browse and install via great-docs skill install.

Learning Resources

If this episode inspired you to up your documentation, packaging, and AI-assisted development game, these courses are good next steps.

Static Sites with Sphinx and Markdown: A free course on building documentation and stand-alone static sites with Sphinx using Markdown as a first-class citizen, perfect background for anyone evaluating Great Docs against the older Sphinx world.
Modern Python Projects: Walks through the full Python project lifecycle, including project structure, dependencies, tests, documentation, CI, and deployment, which is the broader context Great Docs slots into.
Agentic AI Programming for Python: If you want to understand the agent side of the "docs for humans and AI" story, this course shows you how to actually work with agentic, tool-using AI on real Python projects.

Overall Takeaway

Documentation has quietly become one of the most strategic surfaces of any Python project. It is read by the humans who decide whether to adopt your library, and increasingly by the AI agents that will be writing code against it on their behalf. Great Docs is a clear statement of intent: docs should be fast to spin up, opinionated and beautiful by default, executable so the examples actually work, and shipped as Markdown so an LLM can consume them as easily as a developer can. Whether or not you end up choosing Great Docs over Sphinx, MkDocs, Zensical, Mintlify, or QuartoDoc, the takeaway is the same. Treat your docs as a first-class part of your project, design them for both audiences, and lean on the small but tightly collaborating community of maintainers who are making this much easier than it used to be.

Episode Transcript

Collapse transcript

WebVTT format On GitHub

00:00 Your documentation has two audiences now, humans reading the rendered HTML and AI agents making

00:05 sense of your library.

00:06 Rich, I known, and Michael Chow from Posit are back on Talk Python with a

00:10 brand new Python documentation tool called GreatDocs that takes both seriously.

00:15 Rich is the creator of Great Tables and before that,

00:18 the R package GT.

00:19 The man has a serious eye for design and he's pointed

00:22 that energy at the Python Docs ecosystem.

00:24 We'll talk about how GreatDocs spins up a polished site

00:27 and three commands, why every page ships as markdown for your favorite LLM,

00:32 how it leans on corto for executable code blocks and tabbed install sections,

00:36 and where it lands against Sphinx,

00:38 MakeDocs, and Zensical.

00:39 Plus, you'll meet Tablin. Here we go. This is Talk Python To Me,

00:42 episode 549, recorded May 19th, 2026.

01:05 Welcome to Talk Python To Me, the number one Python podcast for developers and data scientists.

01:10 This is your host, Michael Kennedy.

01:11 I'm a PSF fellow who's been coding for over 25 years.

01:15 Let's connect on social media.

01:17 You'll find me and Talk Python on Mastodon, Bluesky, and X.

01:20 The social links are all in your show notes.

01:23 You can find over 10 years of past episodes at talkpython.fm.

01:27 And if you want to be part of the show, you can join our recording live streams.

01:30 That's right.

01:31 We live stream the raw uncut version of each episode on YouTube.

01:35 Just visit talkpython.fm/youtube to see the schedule of upcoming events.

01:39 Be sure to subscribe there and press the bell so you'll get notified anytime we're recording.

01:44 Hey friends, before we dive in, I want to share something I just launched over at Talk Python,

01:48 a new course.

01:49 If you ship Python to production, you've probably had that quiet thought about

01:54 what might be lurking in your code.

01:55 My new course turns that worry into a concrete workflow

01:59 and a reusable AI security agent that's yours forever.

02:02 It's Python Web Security, the OWASP top 10 with agentic AI.

02:07 Check it out at talkpython.fm/AI dash web dash security.

02:11 The link is in your podcast player and on the episode page,

02:14 or just go to talkpython.fm and click on courses at the top.

02:17 It should be right there.

02:19 So if you're interested in making sure the apps and APIs that you ship are secure,

02:23 this is the course for you.

02:25 This episode is brought to you by Sentry.

02:27 You know Sentry for the error monitoring, but they now have logs too.

02:31 And with Sentry, your logs become way more usable,

02:34 interleaving into your error reports to enhance debugging and understanding.

02:38 Get started today at talkpython.fm/sentry.

02:42 And it's brought to you by Temporal, durable workflows for Python.

02:46 Write your workflows as normal Python code and Temporal ensures they run reliably,

02:51 even across crashes and restarts.

02:53 Get started at talkpython.fm/Temporal.

02:57 Rich, Michael, welcome back to Talk Python To Me.

03:00 Awesome to have you both back on the show.

03:02 Yeah, thanks for having us.

03:03 We're going to talk about great things.

03:05 I know it's going to be a great show.

03:06 It's undoubtable, right?

03:08 I have no doubt.

03:09 It's a great day, you know, and we're ready for,

03:11 I think what's going to be a great chat.

03:13 Yeah.

03:14 About great docs, great tables, all of those things.

03:18 All the great things.

03:19 Yeah.

03:20 So I had you on to talk about great tables, which was really fun.

03:23 You all both from Posit.

03:25 And other than that, maybe let's do a quick introduction for folks.

03:29 I mean, I don't know why anybody would not have listened to the great tables episode,

03:33 but in case they haven't. No, we honestly, we get a bunch of new listeners all the time.

03:37 So yeah, let's do a quick round of introductions.

03:40 Who are you?

03:40 What do you do? Why are you working on this project?

03:43 Rich, start with you.

03:44 Yeah.

03:45 I'm Rich.

03:45 I work at Posit, PBC.

03:48 I've been doing traditionally lots of R stuff, like in the past,

03:51 but more lately, this is like the last three or four years,

03:53 a lot more Python stuff.

03:55 And actually Michael, who's with me today,

03:58 he taught me a lot about Python.

03:59 Like I was pretty bad starting.

04:01 I mean, I used in the past, but I was open source stuff. I was,

04:04 oh that was bad michael has so much patience though so uh he'll make up speed over a period

04:09 of a year or so um so i owe a lot to him and yeah that's he's a great guy that's really cool i i

04:16 agree with that i think it's it's hard to change a language it's hard to switch to another language

04:21 and maybe you could speak to that real quick before michael jumps in and just i've done that a couple

04:26 times you know you spend so much time and energy and effort and getting really good at a not just

04:32 the language, the tools, the ecosystem,

04:33 everything.

04:34 And then you're like, I'm one O, I think I have to go over there for a while.

04:37 Yeah.

04:38 It feels like a bizarro situation.

04:39 Like I know what I could be doing, what should be doing,

04:41 like theoretically, but things just don't jive sometimes.

04:44 It's like, oh, yeah.

04:45 But then you, then you get used to it and then your previous language degrades.

04:49 It's kind of like that sort of thing.

04:51 It's a little bit, a little bit sad in that regard, but you know, for me,

04:54 the real challenge was I'm, I have such a deep knowledge and mastery of this technology.

05:00 And if I switch, at least the first time or two I did, I felt like I'm going to go back to the newbiest of noobs and it's going to feel really bad.

05:08 And I was so hard for this knowledge and this experience.

05:13 Why am I going to do this?

05:15 Maybe I should never do that.

05:16 It was really, it was a big deal for me.

05:18 Maybe you could just, I want to say that for other people out there who are not necessarily going R to Python, but just one tech to another.

05:24 Yeah, it's humbling, like I said.

05:26 And well, you know, with a good venture and lots of patience,

05:30 it can happen.

05:31 Yeah, it's good to expand your skills, but the initial decision is rough.

05:34 Michael, you've been shepherding Rich along the way.

05:38 I love it.

05:38 Tell us about yourself.

05:39 I wouldn't even say shepherding, or maybe there's like some mutual shepherding going on.

05:44 So I'm Michael Chow.

05:45 I'm a software engineer at Posit and have been for about four years on the open source team.

05:51 Yeah.

05:51 And I, so I've worked with Rich on things like great tables.

05:54 And I think that, yeah, I'm really interested in Python.

05:57 I work on Python full time.

05:59 I think if I had to send back what Rich is really good at,

06:03 Rich just has this crazy, freaky sense of style.

06:07 And I think that's one thing that's drawn me to work with him on things is you just never know.

06:12 Like, to be totally honest, people at Posit just never know what Rich is going to pull out.

06:16 And I don't think any of us could have imagined it.

06:18 He's a loose, he's our wild card.

06:21 And it's been interesting because you can imagine like a programming language.

06:24 Yeah, you could be like, oh, this person taught me this programming language.

06:27 I don't really know how you teach Rich's style, but I feel like I'm kind of along for the ride. I'm like eating popcorn,

06:32 helping out. And I think tools like Great Docs really reflect that, this interesting sense of style.

06:37 Great tables.

06:38 He's just dipped into this rich history of table styling.

06:42 How would you style it to present and maybe publish it?

06:46 And so I've been excited to be along for the ride to just watch him cook and bring this unique sense of kind of like style and design into tools.

06:55 Yeah, that's really cool.

06:57 You know, certain people just have a knack for APIs and the way that develop,

07:02 you know, the developer UX sort of thing.

07:04 That's cool.

07:05 I personally am excited for the mascot.

07:08 Yeah, Rich, I blew your cover.

07:12 we were yeah so michael and i were talking a little bit at pycon uh about uh tablin how you're

07:18 tablin yes he hasn't been trying out a mascot wizard yeah who is tablin though i wonder he's

07:24 just a little table guy a little table dude that appears gives you help and then disappears just

07:29 as fast um right he hasn't fully realized he's he's he's always thinking of you he's never thinking

07:34 of himself you know he's he's showing up helping you out he's like the new uh the bee or bob but

07:40 much cooler because he's a table and can display things this absolutely yeah and i do think this

07:45 speaks to our dynamic where tablin just appeared one day like well while we were preparing a pi

07:50 con talk two years ago tablin just appeared in the slides and i didn't know who tablin was and i was

07:56 like who or what is this it was like a slide of a table and tablin was popped out on the side was

08:01 saying good job and i was like who's this spreadsheet with eyes and a mouth cheering

08:05 people on and rich was like it's tablin of course yeah it's helpful to have a little dude that just

08:10 wants to help you know it's like having a pet like a cat i love it it's really good so michael

08:18 we had the great opportunity to meet up at pycon just last week i know i don't know how you feel

08:23 about it personally i'm still just a little bit recovering from the whole energy that was extracted

08:29 from me you know but it was really fun and maybe just give us your thoughts on pycon and how'd that

08:33 go.

08:34 Yeah.

08:34 Yeah. It's a great question.

08:36 I, um, it's so interesting because we work on tools for

08:40 data analysis, but PyCon is much more general. It's almost like all things Python.

08:45 I think it's a really interesting conference versus like a PyData or a SciPy, which are way oriented towards

08:51 like data tools specifically.

08:53 Um, but I love it. I find it really nice to be able to drop in and

08:57 talk to just the full range of Python people who maybe have never used or done a lot of data

09:04 So I find it really interesting to talk to folks who maybe almost universally, I think

09:08 everybody has touched pandas, the library for data frames.

09:12 And so that's the like funny kind of like point you can always talk to anyone about at

09:17 PyCon, but I find it really nice.

09:19 And I find the like PyCon organizers and the sort of Python software foundation,

09:25 it's just so down to earth that, yeah, I really love dropping in.

09:29 It doesn't feel super corporate.

09:31 It feels like they're really like a group of passionate volunteers putting this like pretty big conference on.

09:37 So, yeah, I always love dropping in,

09:39 even if it's like a kind of broader audience than the like data crew.

09:44 I'm curious your experience.

09:45 Have you gone to a lot of PyCons?

09:47 I think my first one, when was my first?

09:50 Mid-teens, I would say 2015, 2016,

09:54 something like that.

09:55 Yeah, nice.

09:56 I'd probably have gone to maybe two thirds since then.

09:59 Most.

09:59 I mean, we did have COVID in the middle.

10:01 That was challenging.

10:02 But yeah, I've been to a fair number and I really enjoy it.

10:05 And for me, it's just nice to get together, meet folks like you and everyone else and

10:10 just kind of remember, hey, this is a community of humans and not just docs.

10:15 Never mind.

10:15 I mean, docs are great.

10:16 We're going to talk about how great docs can be.

10:18 But it's also nice to just have these human connections and just connect with people outside

10:23 of with, but also outside of technology,

10:26 right?

10:26 Like, let's just go sit in the sun for a while and talk.

10:29 Like, have you seen The Sun lately?

10:30 No, I haven't seen it either.

10:31 Let's go sit there.

10:32 All day.

10:33 Yeah.

10:33 Yeah, for real.

10:34 I feel like it is.

10:35 Just putting the face behind the name or actually like touching down to chat does seem like

10:40 a huge thing that you only do like say once or twice a year.

10:44 Yeah.

10:44 With those folks.

10:45 Yeah.

10:45 At least for me, I can come back and revitalize to do more.

10:48 So that's really, really sweet.

10:50 Let's start our journey here.

10:54 Talking about, just do a quick review of Great Tables.

10:58 Because I know Great Tables was one of the inspirations for Great Docs.

11:00 So we all both got together, all three of us got together last year,

11:05 I guess, to talk about Great Tables.

11:07 So who wants to just do a quick reminder of this one?

11:11 I'll go.

11:13 So basically, yeah, Great Tables, it's a,

11:15 maybe not many people know this, it's a port of an R package called GT.

11:20 Not that important, but the idea is good as it was then.

11:24 You want display tables, what I call them.

11:26 essentially summary tables like static tables and you want to present them say in a notebook or say

11:32 like in some other publishable document as html we also have a latex output format but the idea is

11:38 you compose tables step by step you know you add a header you want you want a title you get that too

11:44 you structure the table you can format different cells like usually entire columns of cells or and

11:50 you can also style a table which could be like you know like changing orders adding cell backgrounds

11:55 things like that.

11:56 And really the idea is to like to make a table that you might see like in a print

12:00 publication, but using your data, like directly,

12:03 like using a data frame.

12:04 So you have the data in a form which is amenable to a summary table.

12:09 And then in just a few like method calls, you've got

12:13 the table.

12:14 Yeah, that's awesome.

12:15 What strikes me about this, when we had our conversation last year,

12:20 It's just how much more there is to think about with tables than, you know, just an Excel-like thing.

12:27 I came away realizing that it goes way deeper and there's a lot more nuance.

12:31 It felt a little bit like, oh gosh, I can't remember the guy's name, but I'm sure you both have seen his books.

12:37 But it's...

12:38 Is it Stephen Peavy?

12:40 Tufty?

12:40 No, no, no.

12:41 Tufty.

12:42 Tufty, yes.

12:43 Okay.

12:43 He's just like, oh, I see.

12:45 Like there's some lines and stuff like, no, no, no, no.

12:47 Hold on.

12:47 There's a lot going on.

12:49 And like, there's many things you can communicate subtly without just being like, well, let's just call this out.

12:55 Like, no, you don't even have to call it out.

12:56 It's communicated through something more interesting.

13:00 You know, a tough thing is that about just presenting sort of scientific information in general.

13:05 But I felt that way about tables as well.

13:07 Yeah, it's pretty well.

13:08 We talked about this in our talk a few years back in PyCon.

13:12 how like you can tell a story with a table where you can communicate data in a better way in a

13:18 not a more optimized way but a more legible way where like your main point is like describe like

13:23 a title and a subtitle and you have notes at the bottom and you can guide people through an analysis

13:29 summary that way and so just like with many different things there's a good way to do it

13:33 or a better way to do it yeah there's you could just look at certain types of presented information

13:38 and you go, well, that looks really professional

13:41 or that looks really, really good,

13:43 but I don't know why.

13:44 You know what I mean?

13:45 Yeah.

13:45 This looks bad.

13:46 That was good, but I don't, yes, but I can't put my hand or my finger

13:50 on exactly what is really different, but that's really good and that's not, you know?

13:54 And I feel like Great Tables kind of leans into that.

13:57 Yeah, I guess it takes the Tufti principle too, like having just the right amount of ink,

14:02 I guess, like not too much, just enough to communicate

14:05 the structure of things, like the sort of like the architecture of the data you're laying out and not doing much more than that.

14:10 So there's a lot of that that goes into this.

14:13 Indeed.

14:13 As a default thing.

14:14 To the Tufti point too, Tufti's website,

14:17 Tufti has like all of these just dumps of examples, just like example plot,

14:22 example plot, example plot.

14:23 It's almost like a very rough notebook.

14:25 And I feel like with great tables, it was kind of similar.

14:28 Like when I first came on, I knew basically nothing about this topic.

14:33 And I saw the components of the table diagram.

14:36 So you have it pulled up, but it has like a table broken apart into all its pieces,

14:40 like a title, subtitle.

14:42 There's this funny thing called the stub head and spanners.

14:46 And I thought like, does a person really need to know all this?

14:49 But I think to the point of Tufti, like maybe what you're getting out to is Tufti really

14:53 dives into like very specific, almost like dimensions of how you could represent data.

14:59 One thing he gets really into is like sparklines, this idea that like how far could you get with a line that basically doesn't have any axis labels,

15:06 but it's just like a trend.

15:08 Like is it going up or is it going down?

15:10 And that happens a lot in tables.

15:11 You'll put like these sparklines in a cell.

15:15 Like if you're looking at stocks, you'll have like the stock numbers and then you'll have a sparkline that like indicates the kind of trend so people can grab it really fast.

15:23 But I find what's interesting about Tufti is just that willingness to dive in so detailed about this one very specific action.

15:30 And I feel like this table diagram is sort of similar to me,

15:33 the willingness to break it apart so thoroughly.

15:36 At first, I wasn't really convinced.

15:38 It seemed like a lot of work.

15:40 But yeah, I think to your point about Tufti, once you start looking at examples, you start to realize this kind of captures the flavor or design of good examples out there in the world.

15:50 Yeah, I think it's really out there.

15:52 Like initially when I did too, it was like, oh, this is too much.

15:55 But naming things is so important.

15:56 Otherwise, you're just awkwardly describing something over and over again,

15:59 like that cell to the top left or these cells off to the side.

16:03 And eventually you just have to give it a name, even if it's not the best name.

16:06 And these are actually names I stole from like basically a census manual on tables,

16:12 I think written in 1949.

16:14 Great ideas, like wonderful book.

16:16 And it's on the web as a PDF still.

16:19 It's a scam.

16:20 I remember I was talking about that.

16:21 Yeah.

16:21 How interesting is it?

16:23 Yeah.

16:23 How interesting is it that the inspiration comes from pre-digital times?

16:28 Yeah.

16:29 And I think that, yeah, because a lot of the software reduces some of these ideas.

16:34 It's like, well, I have grids.

16:36 I have a grid of cells and sometimes the rows can be taller.

16:39 Sometimes you can span a row.

16:41 Okay.

16:41 That's that.

16:42 But if you just write it by hand when you have to way back in the day,

16:46 it's like, oh, well, maybe we could draw it differently,

16:48 right?

16:48 Yeah.

16:49 Yeah.

16:49 And it's like, I was like searching, like researching,

16:51 like anything on tables I could find just to get ideas and like, you know,

16:54 like what people thought was good.

16:56 And it's really hard to find anything on tables.

16:58 It was like, oh, but I did find that one thing.

17:00 And like, I'm forever in debt to the person who wrote it.

17:03 Yeah, that's awesome.

17:06 This portion of Talk Python To Me is brought to you by Sentry.

17:09 You know Sentry for their great error monitoring, but let's talk about logs.

17:13 Logs are messy.

17:14 Trying to grep through them and line them up with traces and dashboards just to understand one issue

17:19 isn't easy.

17:20 Did you know that Sentry has logs too?

17:23 And your logs just became way more usable.

17:25 Sentry's logs are trace connected and structured, so you can follow the request flow and filter by

17:31 what matters.

17:32 And because Sentry surfaces the context right where you're debugging,

17:35 the trace relevant logs, the error,

17:37 and even the session replay all land in one timeline.

17:41 No timestamp matching, no tool hopping.

17:43 From front end to mobile to back end, whatever you're debugging,

17:46 Sentry gives you the context you need so you can fix the problem and move on.

17:50 More than 4.5 million developers use Sentry, including teams at

17:53 Anthropic and Disney+. Get started with Sentry logs and error monitoring today at talkpython.fm

17:59 slash Sentry.

18:00 Be sure to use our code, talkpython26.

18:03 The link is in your podcast player show notes.

18:05 Thank you to Sentry for supporting the show.

18:09 Let's move on, but if people are out there and they're doing presentations that involve tables,

18:14 and especially if it's code generating those tables.

18:16 Check this out.

18:17 It's quite interesting.

18:18 So the next thing I want to talk about is just sort of surveying the landscape of what is out there,

18:24 because we're going to talk about great docs and great docs can generate static sites.

18:29 So there's some existing tools that generate docs as static site. There's some really good tools that just generate static sites that maybe people

18:36 could put into docs. Like there's a lot of things that are somewhat similar.

18:41 There's also stuff that's in the same space, but different. So maybe we could kind of go through and,

18:45 you know, like I know you all have mentioned Sphinx is a real popular one in the Python space.

18:50 There's MKDocs.

18:52 I had Martin from Zensical on not too long ago.

18:55 So maybe we could talk first about some of the existing tools that are,

18:58 I guess, as similar as possible to what you're doing.

19:01 Yeah.

19:02 Michael, would you like to speak on this?

19:04 Because I know you did a deep dive recently on these.

19:07 Yeah.

19:08 So Sphinx, I think, and maybe to kick off some helpful context to great docs is that, yeah,

19:14 I worked a lot on early support for documentation with a tool called QuarterDoc.

19:18 But Rich actually took it to the next level.

19:21 And this goes to, I think, Rich's style with great docs.

19:25 So I have a lot of bizarre experience looking at the history of Python docs.

19:30 I think Sphinx is one of the OG site builders.

19:36 I think this is the case.

19:38 So I think one interesting fact is, as I understand it, I think Python.org,

19:42 don't quote me on this.

19:43 I think it was originally done in like LaTeX or something like that,

19:46 the Python docs.

19:48 And I think that they moved to Sphinx at some point.

19:52 So like Sphinx has a really interesting history in Python.

19:55 Like if you go back 25, 30 years, Python docs had to exist using some tool,

20:01 right?

20:01 And at some point Sphinx emerged as kind of like this dominant site builder for Python and Python docs.

20:09 Yeah, does it say?

20:10 Yeah.

20:10 So Python docs are in Sphinx.

20:13 you know this python doc site has a how-to python how-tos this is another weird fact

20:19 the how-tos emerged I don't remember exactly when they emerged it was like in the last 30 years I

20:25 think as part of the Linux project so the term how-to as I understand it emerged in the Linux

20:34 docs but all these things like it's so funny we see them today and and maybe it seems we just

20:39 think about like, oh, there's the Python docs,

20:42 but actually at a certain point, you know,

20:44 Sphinx emerged, this concept of a how-to emerge.

20:47 These are all things that over the last, I think like 30 years sort of like came into existence.

20:53 So Sphinx is like the OG doc site.

20:56 A lot of tools use it.

20:57 Pandas uses it to generate its APIs.

21:01 Polars uses it as well.

21:03 So some really big python tools use it to generate their um api docs um it uses this thing called restructured text

21:11 i will say like i don't know that a lot of open tool developers i love love it um i'm going to be

21:18 a bit careful here because i think it's been so useful but i do think that restructured text is

21:24 kind of not the thing most open source developers are reaching for these days um but sphinx is like

21:30 the og uh doc site and it powers a ton of docs like python.org and pandas i'm sure if you know

21:37 i'm sure it was really made a huge improvement when it came out though right yeah i think if

21:41 you're doing a look at before that's got to be yeah yeah it's like zero to one essentially i think

21:47 switching from lit tech to sphinx for like your python docs yeah and if i see an rst file it's

21:53 a little tear wells up in my eye i'm like oh gosh here we go it's a it's almost like a rite of

21:58 passage i feel like as a python developer producing docs in the like sphinx world you just

22:04 kind of like you learn i learned sphinx and rst to generate docs essentially uh it's like yeah i

22:10 feel like that was my rite of passage into like software development 100 so we've also got mk docs

22:16 or make docs probably i don't know i always feel like i say make docs but no i i have no so i mean

22:22 you had the zensical people so i feel like they do you have a read on it if i try to remember i

22:28 like martin said mk docs but whoa i i not he could have easily said make docs and i was not paying

22:35 attention yeah um i'm a doctor so yeah no i think that i think that makes sense a lot of these that

22:42 could be said one way or another i really wish and maybe this does but i really wish on their

22:47 github repo they just have a little mp3 like here's how you say it you know what i mean

22:51 little audio button yeah exactly it's like a green unicorn like g unicorn versus goonicorn is

22:58 like a one that i think goes around and around still yeah okay so zensical is um one of the more

23:04 modern ones so i think that that's pretty interesting i don't honestly i'm not sure how

23:10 much it lands in the sphinx mcdocs world or in the other maybe the just pure static site generator

23:17 side of things i mean the sensical folks came on and probably have the best sense but um my sense

23:24 is it's also meant to be kind of a i might be wrong drop-in replacement for make docs i know

23:28 their community yeah yeah it is a it is a um compatibility at least compatible uh for a material

23:35 for make docs yeah right right right yeah for sure so yeah i would say it's in that in that realm

23:40 it also seems like they're heading towards general purpose or knowledge bases which goes

23:44 maybe a bit beyond just like yes exactly that was my like uncertainty is how do i classify it right

23:50 because it's it doesn't even necessarily if you look at their h2 it doesn't say the best way to

23:56 make your docs right it's it's a scalable way for technical writing right which makes it i think

24:03 land a little more in the hugo or ghost side of um thing so that's another part to part to talk

24:09 about it's just like static sites in general you know why would i choose say sphinx over hugo or

24:15 hugo over sphinx or something like that you guys got yeah it seems a bit like mitlefy they have the

24:19 same sort of thing going to they do documentation sites but they go a bit beyond it's like general

24:25 purpose lots of different languages supported uh but it is documentation but not really so much

24:30 like a site like just general purpose site generator so it's so hugo and ghost i don't know

24:36 goes very well, but Hugo, for example, I use that a lot for blogs. I've seen one of my friends does

24:41 really cool stuff just in general with Hugo making general purpose sites.

24:46 I feel like this is much more focused on,

24:49 I just need a static site and much less, I need it to read my doc strings and

24:54 categorize my modules and, and API calls and put in that kind of stuff. Right. So that's another,

25:00 another realm that is similar to what you all are doing, but certainly not the same.

25:04 Yeah, if you want to throw another one in, there's Korto by the company we work at, Posit,

25:09 and that does sites and much more beyond.

25:13 I do think I had JJ on and I'm so sorry, I'm forgetting the name of the other guy.

25:19 Oh, Charles.

25:20 Yeah, I think it was Charles.

25:21 Oh, cool.

25:21 To talk about Korto a little while ago.

25:23 That was fun.

25:24 Yeah.

25:24 I do think a lot of the questions with like Hugo versus something more targeted at like docs for a

25:30 tool is hitting on kind of like, what are the parts of a doc site?

25:35 You know, like what's technical writing versus like package documentation?

25:39 Am I just doing a Hugo thing? Like is what I'm doing similar enough to like a blog or a website with content,

25:46 which is really common, like my website's in Hugo?

25:50 Or do I need something special to like dump out my like API docs to dump out the things

25:55 from my like functions and classes?

25:57 Or could I jam that into Hugo?

26:00 That's a common kind of hybrid path.

26:02 Could my thing just dump my info into Hugo?

26:05 It's all kind of this dance between really, is this a general content problem?

26:10 Is this a like very specific tool problem?

26:13 Or can I kind of like jam them both together into something.

26:17 Yeah, that's an interesting problem.

26:18 So maybe a good time to start talking about, you know, great docs.

26:23 What is it?

26:24 Like, what's its value prop and positioning with regard to these other areas?

26:30 Well, on your screen, you have package down.

26:32 Yes.

26:33 It has an origin.

26:34 Actually, coming from R, I can't help but to be a little bit influenced by package down.

26:39 I use it a lot in my R projects.

26:42 And I kind of felt like there was like a package downsized hole in the Python docs ecosystem,

26:47 just a little bit, where, you know, you can just point something at your docs and it makes

26:51 something pretty fast with pretty much no configuration.

26:53 That's like the challenge.

26:54 Does it present something that's serviceable, like usable right away?

26:58 And that's what I was shooting for.

26:59 And I think that's kind of like where I landed.

27:02 And of course, we have tons of options to do way more things.

27:04 But I wanted to give something that was, you know,

27:07 you just start it right away and it gives you something.

27:10 Like, for instance, you have doc strings and such,

27:13 and they all just get captured and put into the API reference section.

27:18 And then later on, you would, you know, attend to it and organize it and then, you know, arrange it and exclude things.

27:24 At the very beginning, it would just give you something at least.

27:26 So that was kind of like my goal.

27:28 The up and running super quick is one of the themes, right?

27:32 Yeah, yeah, absolutely.

27:34 Because I think, I suspect, maybe a lot of people are getting more into Python now because of agents, AI, LLMs,

27:41 and such, and are spinning up small projects.

27:43 And maybe they're even building their documentation sites with using the same things, like LLMs.

27:50 So getting something up quickly.

27:52 And maybe the project doesn't last very long.

27:54 It's just like something just to get going.

27:56 And you don't want to spend a ton of time on learning the docs,

27:59 a new doc system.

28:00 So this sort of thing is pretty valuable.

28:02 But we still give you the opportunity, of course, to,

28:04 you know, like add things and do really cool,

28:06 sophisticated sites.

28:07 But just the up and running part, it was super important to me.

28:10 So by default, you can point it at a package or set of Python files or something and say,

28:15 generate docs around that.

28:16 And it will look for doc strings and so on, and then generate some kind of hierarchical.

28:21 Yeah, exactly.

28:22 And we tested it quite a bit on different package layouts,

28:26 like, you know, different packaging systems.

28:28 And it seems introspect pretty well based on all sorts of variation.

28:32 and we do test this a lot.

28:34 So the promise is that it does give you something.

28:37 And you can also create just more static site type stuff as well, yeah?

28:41 Yeah, oh, absolutely, yeah, you can.

28:43 I think the user guide's a good example.

28:45 Like if you click the expandable thing in the top left.

28:49 Yeah, everything's so zoomed.

28:51 Yeah, everything's so zoomed on my little small streaming screen.

28:55 So yeah, the user guide got it.

28:57 It's nice, the user guide's just a folder in the repo with files in it.

29:01 But it's nice like that that puts up this like, yeah,

29:06 more kind of general bit of content where it's not your API reference,

29:12 which is like each individual function explained, but a more general kind of guide,

29:18 kind of like a bigger, higher level, like introduction to the package.

29:23 But it's nice that to your point, like, can you have more general kind of content?

29:27 It's nice.

29:27 This is just a folder in the repo.

29:29 So getting started with the user guides, like super fast.

29:32 Yeah.

29:33 And this site is like a demonstration.

29:34 We're showing like the great docs site and we're just looking at it and you can just

29:39 add another directory and like recipes at the top nav.

29:43 That's just another directory.

29:44 And we sort of declared it in our configuration file.

29:46 So you can just create something similar to a user guide.

29:49 But we sort of treat a user guide as a sort of like a first class thing because we,

29:53 well, I'm a little bit opinionated about how sites, these doc sites should be.

29:58 So it kind of serves as a model.

29:59 So like the idea is that if someone sees this and says, yeah, I would like something like this,

30:03 then like three docs would be a good fit.

30:05 You just have sort of emulate what we have here, do a few things and you've pretty much got it beyond the simple sort of like init and then like build.

30:12 We can just go a little bit beyond.

30:14 Yeah, sitting here talking to you makes me think, you know, I've got some open source projects.

30:18 I really should have better docs with him.

30:19 Maybe.

30:20 Maybe I'll try working on them with great docs.

30:22 That would be really fun.

30:23 Oh, yeah.

30:24 And I love your feedback.

30:25 I'm always looking for ideas and feedback.

30:27 Right now, I'm not going to make a big deal of it.

30:30 But I'm looking for users because this is a brand new project.

30:32 So feedback is a bit scant at this point.

30:35 So yeah, let me know how it goes.

30:37 Yeah, I will definitely.

30:38 One of the things that's nice here that I'm noticing is it's got a lot of elements of the

30:43 display that go beyond just standard markdown that i think are really nice like for example

30:49 you've got these oh because these are probably like little tags or badges yeah yeah and then

30:55 also you've got a tabbed ui for like here's how you install it on mac Linux windows but in the

31:02 same little area right you just like click the tab for your os yeah because tab sets in cordo

31:06 they're like a cordo special really they just come part and parcel with cordo yeah yeah i feel like

31:12 you can do some nice authorship beyond that.

31:14 Like when I was working on my book, I'm like,

31:16 I'm going to write it in Markdown, but I also want to have these little call outs

31:19 or like an action or, you know, the little sidebar,

31:22 like how in the heck am I going to get that to come out of Pandoc?

31:26 You know what I mean?

31:26 Yeah.

31:27 I eventually got it to work by basically getting a little pre-parser

31:32 that would just turn those into HTML and allow the Markdown to have HTML.

31:35 I think that's what makes a good user guide a good user guide.

31:39 We actually show, like, not just like show the code,

31:41 but actually show the results.

31:43 And you can totally do that with a good user guide.

31:46 And that's what I try to demonstrate here in the Great Docs user guide

31:50 that we have these things.

31:52 Here's how they look.

31:53 You can have these too.

31:54 Yeah, that definitely looks good.

31:56 That's the one thing too with Quarto that if I had to make the case for Quarto

32:01 for a lot of people doing documentation, it's that it's really easy to run code.

32:06 Running code is kind of like most of Quarto's game.

32:09 It's a you author using a QMD.

32:12 It's essentially a markdown file, but your code blocks can be executed.

32:17 So it's really inconvenient for docs, like being able to include code snippets with their out and then they get run and their outputs are there.

32:25 So that's kind of the impetus, I think, in this case for Bordeaux is doing like really easy execution of code.

32:33 It's possible in other tools.

32:35 And I know MakeDockstrings, who I think its author is working with Zensical now too.

32:41 But they've created a lot of good ways for you to be able to do this as well, like execute code.

32:47 But I do think that's one area where people stub their toe a lot is like,

32:51 oh, like if I'm Polars or Pandas, I'm a data frame library.

32:54 I probably want a lot of examples.

32:56 And then you get stuck in this like funny dance, like how do I execute the code for my examples?

33:01 And so I think tools like Quarto are really kind of aimed at that.

33:05 use case like you're a person running code and generating reports you know that that have code

33:11 and that produce graphs and tables and yeah and i think the examples like being executable made the

33:17 great tables examples really powerful you can see the code for a table and then see the table

33:23 right below like in the actual like site which is we didn't have to paste that in it was basically

33:27 just generated right there yeah that's amazing which is actually incredibly you can put pros

33:31 around it as well so it's like it reads just like a little mini guide in each doc string does it

33:38 run at build time or does it somehow run in the website oh build time yeah yeah yeah you guys

33:44 embedding WebAssembly or something fun like that no you could do that you could do that yeah i

33:49 another nice thing you can freeze it so like if you have a bit of code that um or like let's say

33:55 you have a blog post and you don't want to rerun it every time because like over the years maybe

34:01 you like know the code's going to get out of date or it takes a long time to run.

34:06 You can do something called freeze.

34:07 You can quarter freeze it.

34:09 And that essentially like caches the outputs so that you can re-render it without executing the code every time.

34:18 So that's useful.

34:19 Like great tables, we have kind of a growing log of blog posts and we don't want to re-execute them

34:25 every time because that starts to get pretty time consuming.

34:28 So we can just freeze their outputs and then they generate super fast.

34:33 Another reason you might want to freeze it is you're doing accessing live data

34:37 off an API or website and you want to talk about the results.

34:40 And if it changes, like all of a sudden your pros is like,

34:43 why are you talking about this?

34:44 It doesn't say that.

34:44 Well, it used to when I did it.

34:46 You might imagine like a benchmark section example if it runs a long time

34:49 or you just, you know, accessing some keys on your personal machine.

34:53 Absolutely.

34:53 Freezing is great for that.

34:54 You basically froze stuff on your personal computer and you're just like,

34:58 you know, sending it off to like CI.

34:59 high.

35:00 And I think there's like a million, there's also like a million of these things that you

35:04 encounter when you start generating doc sites or like personal content,

35:09 which is like, yeah, maybe I don't want to run some stuff.

35:12 Maybe I want to like include a snippet from one thing somewhere else,

35:16 or maybe I want to do like all kinds of like output customization.

35:22 I just feel like there's a million little boxes to check.

35:25 So that's, that's one.

35:28 I mean, one other reason we use Kordo is we belong to the company that created Kordo.

35:32 But I think those like little pieces of detail for people generating like scientific documents and stuff goes a long way.

35:39 It's pretty wild too, because Kordo has a pretty big extension system as well,

35:44 like pretty active.

35:45 So there's like ways, I mean, besides like different output types,

35:48 there's like extensions, and different types of extensions too,

35:51 like different classes of extensions.

35:53 So it goes really deep.

35:54 Yeah, Quarto is really neat.

35:56 This portion of Talk Python To Me is sponsored by Temporal.

35:59 Ever since I had Mason Egger on the podcast for episode 515,

36:03 I've been fascinated with durable workflows in Python.

36:06 That's why I'm thrilled that Temporal has decided to become a podcast sponsor since that episode.

36:11 If you've built background jobs or multi-step workflows,

36:14 you know how messy things get with retries, timeouts,

36:17 partial failures, and keeping state consistent.

36:20 I'm sure many of you have written brutal code to keep the workflow moving and to track when you run into problems,

36:26 but it's trickier than that.

36:27 What if you have a long-running workflow and you need to redeploy the app or restart the server

36:31 while it's running?

36:32 This is where Temporal's open source framework is a game changer.

36:36 You write workflows as normal Python code and Temporal ensures that they execute reliably,

36:41 even across crashes, restarts, or long-running processes while handling retries,

36:46 states, and orchestrations for you

36:48 so you don't have to build and maintain that logic yourself.

36:51 You may be familiar with writing asynchronous code using the async and await keywords in Python.

36:57 Temporal's brilliant programming model leverages the exact same programming model

37:01 that you are familiar with, but uses it for durability,

37:04 not just concurrency.

37:06 Imagine writing await workflow.sleep, time delta,

37:10 30 days.

37:10 Yes, seriously, sleep for 30 days.

37:13 Restart the server, deploy new versions of the app.

37:15 That's it, Temporal takes care of the rest.

37:17 temporal is used by teams at netflix snap and nvidia for critical production systems

37:22 get started with the open source python sdk today learn more at talkpython.fm/temporal

37:28 the link is in your podcast player's show notes thank you to temporal for supporting the show

37:33 and you all keep talking about cordo because it's the foundation of what's happening with

37:38 great tables right it's been a while since it was um been a while since i had jj and carlos on

37:43 the podcast to talk about cordo but so maybe just give folks a bit of a refresher of what is cordo

37:49 and then how that relates back to great tables um yeah so cordo is a like a like open source

37:55 publishing system so you can make things like sites um like documents like books for

38:00 instance uh you can make presentations uh it's probably a few more i'm missing and it's cross

38:05 language as well and it and like you know code cells so it has computational notebooks is what

38:10 they call them because they have cells which are basically computational cells which can accept

38:14 which have different engines so you can like say like run some r code run some python some julia

38:19 uh what have you many other things as well and then you can stitch them you know basically render

38:22 them into into documents using handdoc for the most part and probably other things too for

38:27 different output types and it just really batteries included has things like you just see in them on

38:31 the site citations cross refs you know it's it's got it all essentially and so how it relates to

38:37 to QuoraDoc and to GreatDocs.

38:41 We're using QuoraDoc.

38:43 But not really.

38:44 I think with QuoraDoc, the way I see it is like,

38:49 and correct me if I'm wrong, Michael, at QuoraDoc,

38:51 you're creating a reference API, but you're still basically using QuoraDoc.

38:55 You're within the QuoraDoc itself.

38:56 You're still creating the Quora config.

38:59 But with GreatDocs, it's kind of like QuoraDoc is a bit sort of like

39:02 we're using it, obviously, but you don't have to know a lot about QuoraDoc.

39:05 you can basically get by with just a few things you see,

39:08 you know, in like the user guide and not have to like go deeply into Quarto.

39:12 It sort of like hides it a little bit or doesn't really advertise it as much,

39:16 even though we're using a lot.

39:17 Just for some context.

39:19 Yeah.

39:19 I mentioned before I developed a tool called QuarterDoc,

39:22 which is another documentation generator for Quarto.

39:26 So just, just to clarify like the context.

39:29 Yeah.

39:30 Like QuarterDoc is a much more kind of like low level, no frills.

39:33 So like the IBIS project uses it.

39:37 So that's another pretty, pretty big Python tool,

39:40 but it's like very like simple.

39:42 It's more about like dump your API reference and then you're responsible

39:46 for like customizing your website.

39:48 And so it's for people who really want to like be in control and set it all up.

39:51 I think Rich is kind of underselling.

39:54 I think great docs is just dripping in style.

39:56 I think that's the, one of the keys is it's made to be kind of like an all in one,

40:01 something really nice out of the box that's opinionated.

40:04 But I just want to clarify for context, QuartoDoc is another tool outside of Quarto.

40:09 So I know we've checked a lot of tools out.

40:12 But one thing that's interesting is I know, like when we look at great docs,

40:17 it's easy to see like some of the stuff that jumps out.

40:20 But there's actually, I think to Rich's credit,

40:23 there's a ton of like little things inside great docs that you almost don't notice until you need them.

40:29 Like there's a million little pieces to doc sites.

40:32 And some of them are actually pretty intriguing.

40:34 Like if you go to the great docs API reference, I think it kind of like speaks to Rich's style that he's included a ton of stuff out of the box for this,

40:46 including this little like filter bar.

40:49 So if you click on the top left, there's a,

40:52 you can sort of like filter on the page for different pieces.

40:55 That's like, yeah.

40:58 I think for just to illustrate the difference.

41:00 So quarter doc is a really bare bones tool.

41:02 It's like we generate an API for you.

41:05 Great docs like this thing, this filter bar where you can like type in it and it shows you live on the page.

41:10 Like it filters your reference items.

41:13 That's just pure rich, just like wilding out on what docs could be.

41:18 And I think there are like a million little examples of this kind of in great docs.

41:23 Kind of. Yeah.

41:24 Cause like I find little things that annoy me and I want to fix them.

41:27 But, um, uh, and so this is my,

41:30 this is almost like a, like a, like a Python site generator

41:34 for, for me in lots of ways, but I'm hoping that other people feel these little pain points

41:38 as well.

41:38 I've certainly felt I've gone to, um,

41:41 documentation sites and search for stuff on there.

41:43 And then you see a little spinner searching, searching static site.

41:47 What are we doing?

41:48 Why am I waiting?

41:49 This doesn't make any sense to me, but okay.

41:51 Yeah.

41:51 Even the CLI button, like, oh, sorry, if you click that,

41:56 that's like if you have a command line interface for your tool,

41:59 which is so hot today, like AI loves command line interfaces.

42:04 Cloud codes just bash executing everything.

42:08 You know, a lot of people have CLIs.

42:11 I think it also speaks a lot to Richestile that he created this spot for your CLI docs to live.

42:18 Very important.

42:20 And then at the top right, if you look, there's like a copy.

42:24 You can copy the whole page to Markdown or view it as Markdown.

42:28 I never would have thought of that.

42:30 To me, I would never go that far to give people something nice.

42:34 I don't know if I'm just like a curmudgeony engineer.

42:37 I think Rich is just dreaming up, I don't know, different ways you could interact with docs,

42:43 copy the page to Markdown.

42:44 And I don't doubt that it's incredibly useful.

42:47 To me, this strikes me as like...

42:48 I think it's very useful, yeah.

42:49 Yeah.

42:50 When I saw that table graph for great tables, like breaking apart the table into every little piece,

42:56 this strikes me as rich again, like imagining every little thing a doc site could do.

43:01 So I think that's why I'm so kind of gassed up about great docs.

43:05 This is delightful.

43:06 And we're going to come back to AI stuff later, but we don't have that much time left,

43:11 honestly, guys.

43:11 We've been talking and not making a lot of progress because it's really, we're just diving into it.

43:15 Docs talk.

43:15 It's so fun.

43:16 I know.

43:16 It's so fun.

43:17 But I can easily see I'm working on a project and I've got Claude or some codex or whatever,

43:24 and it's just not getting it for a certain function.

43:27 Just go over to the docs, hit copy pages, markdown, and just go, no AI,

43:31 this is the docs, read it.

43:33 Because giving it a markdown result of what this is versus all the nav and all the stuff,

43:39 and it's trying to understand what's the essence of the page, if you tell it to just go to the page,

43:44 really, really different.

43:45 Yeah, it's been more immediate, I think.

43:47 Also, you can change the URL if you really want to, to.md and just give it the URL.

43:51 So many ways to do it.

43:53 Yeah, yeah, yeah.

43:54 I love that.

43:55 So it said html.md.

43:56 Yeah.

43:57 Yeah.

43:58 That's really cool.

43:59 So if you were plot code or reading the docs, you know, a lot of good stuff.

44:03 Yeah, season tokens.

44:04 Yeah, yeah, yeah.

44:05 That's cool.

44:06 Did I do that for Talk Python?

44:07 I think I did.

44:08 Yeah.

44:08 You do that on Talk Python, by the way.

44:10 You can just put.md on the end of any episode name, and it gives you the markdown equivalent

44:17 that as well so which is all the rage yeah so i mean we're on the same vibes here i'm loving it

44:21 you know what i mean and it might even help for context i'd be curious to hear your like when you

44:27 added that markdown and some of your motivation for markdownifying your site i didn't do it for

44:32 people i did it for ai and seo the machine stuff yeah for the machine so um i i added a i did an

44:40 llms.txt to try to get the ais to understand the podcast better and some of the things that i gave

44:47 was this ability to just put Markdown at the end, but also I added like a CLI and an MCP

44:53 and different things for an API, search API.

44:56 I'm like, okay, AI, there's 7.5 million words of content over 11 years.

45:01 I want you to know about it and be able to use it.

45:03 How many ways can I imagine giving something to it?

45:07 And this render as Markdown was certainly one of them.

45:09 I also added some silly stuff that's like for, just for me,

45:14 because I've got, for example, I've got to update,

45:17 say, the YouTube recommendations.

45:20 So, or listings after the live stream, I want them to have like links and stuff.

45:23 So I can say dot YouTube on the end and it gives me the contents for like the YouTube render.

45:29 So it kind of was building on this, like how can I help myself be more efficient,

45:34 but also machines?

45:35 So anyway, that's the story.

45:36 This is great.

45:36 It's like Doc's workflow really, right?

45:38 It fits in nicely.

45:40 You know, circling back around, I'm really impressed with some of these little nuances

45:43 that are super nice.

45:45 I think that's great.

45:46 Great talks.

45:46 If you want to go further on this, it's basically just nicing up the docs

45:50 and make them good for humans, but also consumable by LLMs or agents and such.

45:55 Rich, it's a fad.

45:56 We don't really need to worry about it.

45:58 It's going to go away.

45:59 It'll pass, yeah.

45:59 The bubble's going to burst.

46:00 We can just ignore it.

46:02 It's going to be fine.

46:03 No.

46:04 So let's talk.

46:06 I want to talk about a couple of things here.

46:07 So let's just do like a real quick little walkthrough

46:10 of maybe getting started with this.

46:13 It's honestly not a whole lot to get started, but give us this.

46:17 One of you all walk us through the quick start just so people know what's involved.

46:21 Yeah.

46:21 So really that command, like great docs init,

46:24 that'll make the file that is basically what you need for the build.

46:27 And with a lot of testing, it should work on many different Python package layouts and

46:32 types.

46:33 So you just need that.

46:34 Of course, yeah, install great docs, install Porto as well.

46:37 So we got that as well before that.

46:40 But once you have those things, it should do what it says on the screen, basically show

46:43 you stuff in the terminal, which is all positive.

46:45 It's creating that great docs.yaml file.

46:48 And it should be pretty minimal what's in there.

46:50 It should actually also be a little bit dynamic.

46:52 Based on your project, it'll craft the correct great docs.yaml file or the config file.

46:59 And then you could go ahead and customize, but you might just jump to building your documentation

47:03 because that's the next easiest thing.

47:05 It's just another command, great docs build.

47:07 and what you get is a great hyphen docs directory in your working directory.

47:14 And that contains like the site folder.

47:15 But you don't really have to worry about that because you have another command called great docs preview,

47:19 which will basically launch like a web server and then put the site in your default browser,

47:27 basically just like let you see the site locally.

47:29 And then because I'm a big fan of like people know what's going on,

47:32 so it should be totally a black box.

47:34 I give on this page, like a structure, the basic structure of like how it should look

47:39 in your working directory.

47:40 But that's kind of it.

47:41 And I believe the next step for most people will just be getting this on CI if they're satisfied

47:45 and then just working from there, like modifying their initialization,

47:49 not initialization, their config file to give the site more customization personality

47:55 and there'll be authoring guides and things like that.

47:57 You've got the really nice watch feature.

48:00 So great docs build --watch.

48:02 Yes.

48:02 Which feels very Hugo to me.

48:04 Like you're going to build it so you can look at it, but then you want to edit it.

48:07 So just, if you see any changes, just rebuild,

48:10 right?

48:10 Yeah, exactly.

48:11 Small sites will build fast, but this is way faster, obviously.

48:14 So yeah, this is pretty essential for iterating,

48:17 especially initially.

48:18 Yeah.

48:18 And what about this version?

48:20 So this is an interesting aspect of the project.

48:22 Versions.

48:23 Well, essentially you may have, you know,

48:27 multiple tagged versions of your site.

48:29 And this, this is kind of like a wild thing.

48:31 You can have different documentation sites based on your version because you have,

48:36 for instance, new things in your API.

48:38 Right. People maybe know that from Python where you can go up here and drop down.

48:41 Exactly. Like version selectors.

48:42 So this is kind of like just seeing like certain versions of your site and it gives you a selector.

48:46 On the GreatDocs site itself, we have a selector which is maximal.

48:49 It has like every single version from the very first.

48:52 And you can cruise in there and you'll see that there'll be way less in the earliest versions.

48:56 Like the, if you look at the user guide for 0.1,

49:00 which gives a little icon, a little scary saying it's unsupported.

49:02 If you look at the user guide, it's pretty sparse.

49:04 Like it's, you know, it's not as long as the other one.

49:07 And if you look at the reference as well, it'll have less items.

49:11 So it's aware of like what's available in which versions.

49:15 And so you sort of set that up yourself or you can just do it through that command.

49:19 Is that based on get tags or what is that?

49:21 Based on get tags.

49:22 Yeah, that's right.

49:22 Okay.

49:23 I was wondering how does it even know?

49:24 Yeah, you have to give it some information.

49:26 Like you have to, of course, get the tags, but if you actually configure it to do what's doing here,

49:30 like make the site, you just change your configuration to have,

49:33 it's basically just like a small config that you have to do.

49:37 And you can set labels and things like that.

49:39 Can I wildcard it or have it somehow pick up all the versions?

49:43 I mean, you don't want to pick up all tags, but it'd be like star dot star.

49:47 I don't think we have version expressions like that yet.

49:49 Yeah.

49:49 Not yet.

49:50 Okay.

49:51 You know, throw it in there.

49:52 I'm just thinking if I have a project with 27 versions over time.

49:56 Yeah, you probably wouldn't do it through like this interface,

49:58 like Great Docs build.

49:59 This is just for like a pretty quick comparison.

50:02 But if you would do it, like you probably put that in the config file and you'd have to

50:07 manually edit those.

50:07 But I think with a slot or something like that would be better.

50:10 And there's an API, of course, if you want to just have a little control.

50:13 Yeah, it's kind of, you wouldn't do this,

50:14 but it's just, I threw it in there.

50:16 Well, probably because your commands use that,

50:19 right?

50:19 Yeah, exactly.

50:20 Might as well just let people know that.

50:22 Just being transparent.

50:22 I suppose. Yeah. Where do we want to go next? Let's, let's cover just a couple,

50:26 couple of remaining things here while we're, we got time to have, what about open source

50:31 sustainability?

50:32 Like I know you all at Posit are doing a lot of things to open source

50:36 your work and so on.

50:37 Yeah.

50:38 Well, we're pretty much like full-time doing open source work.

50:41 So essentially, and so I think these projects have like long life cycles with the same maintainer

50:47 for long periods of time, which is great for project stability and things like that. And like,

50:52 you know, we're accountable for like, you know, issues that come in and for, you know, releases

50:56 and making sure, you know, it's not, you know, like dead projects,

51:00 you know, like all the way down or whatever.

51:02 So I think, I think that's a great thing.

51:04 And for instance, like great tables, I've been at this since the beginning,

51:07 GT, which is where it came from since 2017.

51:10 So I think that helps a lot. Adds a lot of credibility to these projects that are not just being abandoned.

51:15 There's no fear of it being abandoned or things like that.

51:18 There's, there's a person there at least.

51:20 Yeah, and I think Posit's found an interesting business model

51:23 that's been long-term sustaining, but still allows you, as you said,

51:28 to sort of work in open source.

51:30 Michael, we're joking.

51:31 Yeah, it's really interesting.

51:33 And it's almost like not diving crazy deep and doing a podcast.

51:38 My favorite thing to say to people is that we have a really large open source engineering team,

51:42 dozens of open source engineers.

51:44 People often ask, how does Posit pay the bills for people to work on open source?

51:49 And my favorite thing to say is like, we have a bunch of boring enterprise tools and I'm

51:56 no shade on pause.

51:57 I actually think that this is the best case scenario.

52:00 Like we have a lot of tools that solve really painful problems.

52:04 If you're an enterprise, they could be useful in other settings,

52:07 but it's like, how do I run a report every day?

52:11 Or how do I host like Jupyter notebooks or VS Code for my say like data team or our studio?

52:18 Those essentially pay the bills.

52:20 That's Posit Connect and Posit Teams.

52:22 You've got a team of data scientists, but you don't necessarily have a DevOps team,

52:26 but you still want to have their stuff running reliably,

52:29 right?

52:29 Yeah, and it's a hard problem.

52:31 If you're a company, right, these are kind of tricky problems.

52:33 Or you have like a really mean IT team.

52:37 A cruel IT team could hamstring you for years.

52:41 But that's just to say we get to work on open source because these tools exist.

52:46 And I think Posit exists, I think, because the maintainers care so much about open source.

52:53 I will say in terms of sustainability, one interaction I've really liked over the years is like in the docs realm,

53:02 there's this person.

53:02 I only know him as Pawe Moy, his GitHub handle.

53:06 I think it's Maté or Timothy in France, I think.

53:11 But he maintains the tools upstream of tools like Portadoc and GreatDocs.

53:17 And we've interacted a bit in the past where I've done PRs on his tools.

53:22 One's called Griff.

53:24 And I think that's such an important part of sustainability too,

53:27 is that he works on a documentation tool, MakeDocStrings.

53:31 But we're all able to collaborate on his tool, Griff, that actually powers all of our documentation sites.

53:37 So I think that's a really important piece.

53:40 I think to your point about being at PyCon and seeing people,

53:43 I think us as open source maintainers chatting and even contributing and working on say like upstream tools is

53:50 a really important part of keeping the ecosystem healthy and sustainable.

53:54 We're not like multiple doc tools competing to a degree.

53:58 I do think they compete, but ultimately like we're working on open source because we're

54:03 passionate.

54:03 And I think it helps to collaborate on our kind of like shared tools.

54:07 A hundred percent agree.

54:08 Very cool.

54:09 Now, Rich, you mentioned that pretty new project.

54:12 Yeah.

54:13 Where are we going?

54:14 What's on the roadmap?

54:15 Yeah, lots of things.

54:16 I even have a roadmap on the site if anyone's interested.

54:20 But I think it'll be like a lot more like documentation for different things, like new things.

54:25 Like the other day, I was suggested to create documentation for MCP servers.

54:29 I was like, good idea.

54:31 We don't really have that.

54:32 And it's pretty easy to document JSON, essentially.

54:36 So we can take that apart, parse that, and present something.

54:38 that's a good point because if you look at the mcp servers they don't have structure in the way that

54:44 traditional projects do right they don't just have like a separate function for each thing they've got

54:49 this kind of weird invocation entry point where you pass like the tool you want to use and yeah it's

54:56 documentation suggestions things like that uh so i think we could do a pretty good job there that's

55:00 the idea is pretty new but like i guess we're yeah just trying to be where or go where things are

55:06 going and be a little bit ahead so would that somehow show itself as like where you've got the

55:12 um the api and the cli would there also be an mcp or what do you think it's gonna be a bit crowded

55:16 so i'm rethinking i know yeah yeah i was like i don't really know this would be it like but no

55:20 that's not quite it there's you know maybe one or two more things uh so it might be just a drop down

55:26 nav on the top like a drop down on the top nav so that's part of the part of like uh what i

55:32 have to think about.

55:33 But there's things like that. And also like a recent thing we just did,

55:36 and this is very new, so it's almost like it's new enough,

55:40 is like skills, like publishing skills and making them available and making them browsable,

55:45 right?

55:45 So on the very, it's not top level.

55:47 If you go to the first page, there's like a sidebar on the right,

55:49 which gives you a lot of metadata.

55:51 And one of the first few things is skills.

55:53 And that gives you like a page on how to install these skills. So it's kind of like a,

55:57 almost like a way not to just distribute, but a way to sort of

55:59 like get ahold of skills.

56:02 And there's a nice little sort of like disclosure there,

56:04 install these skills, it gives you instructions on how to do such things.

56:08 And you can just browse the skills below and see what's there.

56:11 You might just take bits of them, make your own skill,

56:13 or you might just say, no, these all look good.

56:15 I'll just follow these instructions and install them for my project or globally.

56:19 So we're trying to make that a bit easier.

56:21 Yeah, it's super cool.

56:22 Yeah, that kind of brings me to the last thing

56:24 that I wanna talk about is the AI-ification.

56:27 And by that, I don't mean, How do I, are you using AI to write it or not?

56:32 Like I imagine there's some degree of that or whatever,

56:35 but if I am a person with a project package or something I want to document,

56:40 AI is really good at going like, well,

56:42 let me pull out all these pieces and then like,

56:45 you know, sketch some stuff out for you.

56:47 Is there, you know, and I can see now

56:49 that you pointed me in the right direction that there's a whole AI section,

56:52 like how do AIs work with great docs, right?

56:55 And so you've got the llms.txt, which is really nice.

56:59 you know, I referenced that before.

57:00 People don't know there's an, this comes from, I believe from Jeremy Howard.

57:04 Yeah, that's right.

57:05 Yeah, we looked at this closely, yeah.

57:07 Putting, yeah, so did I, and I find it super interesting.

57:09 Like this, the idea is that if you,

57:11 you know, there's a robots.txt and a sitemap.xml.

57:15 These are standard web things on sites that humans rarely use to get any value from,

57:20 but machines and traditionally search engines really,

57:24 really do.

57:24 And so, well, what do we put for AI to make it better, LLMs and so on?

57:28 is this llms.txt file that describes in Markdown to the LLMs, like how you can better work with this.

57:34 With that, you all have that, right?

57:36 So you've got your llms.txt and the full one.

57:41 You know, this is not something I'm doing.

57:42 Maybe I need to do a full one.

57:43 This one's interesting.

57:44 It's a lot.

57:45 So basically it's the entire bit of documentation distilled down, not distilled,

57:49 but like written as one file, essentially.

57:51 All doc strings mashed together, you might say,

57:53 including guide material as well.

57:55 So that's all in there.

57:55 Yeah, and you've got these skills as well, which is looking super interesting and also a pretty neat,

58:00 the CLI that you've created a couple of things on that.

58:03 First of all, that it will actually install the skills.

58:06 Yeah.

58:07 So if you're an author, you would just use great docs,

58:11 install, skill install, and then they may be the name of your library for other people.

58:15 That's what other people would see on their sites.

58:16 That's an interesting piece.

58:18 Cause if I'm an, I have to admit, I haven't seen the skills piece a lot,

58:21 but if I'm understanding rich too, this means great docs is also for like kind of all users,

58:26 right?

58:26 Like people who are interested in reading or consuming docs or using it with AI.

58:31 Is that right?

58:32 I see.

58:32 So that's kind of where we're going more and more.

58:34 Yeah.

58:34 So it looks like you're really leaning into making great docs,

58:37 something that works well if you're trying to generate docs and maintain with AI,

58:42 right?

58:42 We also want, if you point your agent at this site, it should be able to find these things

58:47 pretty quickly.

58:48 And you can actually like use tools.

58:49 Like there's one called whatdoagentsc.runtime.app.

58:53 Just search it up.

58:54 You can put it in your URL and it'll show you what pieces are picked up by different agents.

58:58 It actually simulates it really nicely.

59:01 And I found that this sort of validated things that different agents do pick up LLMs.txt, LLMs.full.

59:07 And there's other little pieces of metadata, things that go in the meta tag that can be picked up to like robots.txt and very accept,

59:16 things like that.

59:17 So we're working towards making this even easier.

59:20 Like you just point at the site or point at any site that you author using great docs and your agent should be able to find things pretty quick.

59:27 Very exciting.

59:28 I love it.

59:29 Okay.

59:29 And also just you mentioned that there's the CLI, right?

59:33 Or I don't know what I was mentioning.

59:34 But the fact that there is a CLI is another really great enablement.

59:38 You can say, hey, Cloud or Codex or any of these tool using agentic AI is just like, here's the CLI to do the things.

59:44 Here's the docs and the skill.

59:47 Make this happen.

59:47 You know, right?

59:48 Yeah.

59:49 And you can even, the skills I include, like in great docs could be used to author your

59:54 own great doc site.

59:55 Like there's all sorts of things in there for like just how it works and like, you know,

59:59 like, like writing pages, they're kind of split up into like multiple name skills.

01:00:04 So you can, you can just use that or make your own skills.

01:00:07 Yeah.

01:00:07 Very neat.

01:00:08 All right.

01:00:08 Two really quick things.

01:00:09 I know we're pretty much out of time for you guys.

01:00:11 One, what I get out of this is just a static site and I can just host it on any static

01:00:16 site place.

01:00:17 Okay.

01:00:17 That's really good.

01:00:18 For sure.

01:00:19 it could be netlify it could be you know pages for me on provide some fine grained instructions

01:00:26 for different uh hosts and things like that github pages like seems like a nice default

01:00:30 it's not you know but of course yeah netlify versal things like that we provide some hints

01:00:35 that it works for me i i was running on netlify for a while but i actually had my monitoring

01:00:40 software monitoring it and it actually went down surprisingly often i'm like why is my static site

01:00:45 going down this makes no sense so i've ended up recently i've already got like a big server with

01:00:50 tons of sites so i just i'll just have a config on nginx that just runs it you know and so there's

01:00:55 a lot of options there yeah it's so interesting not not to dwell on it but i do remember you saying

01:00:59 i think on a podcast with um hugo talking about your hugo van anderson your approach that you're

01:01:06 you have way less downtime than even some of the cloud providers so not not to go too deep

01:01:11 that's interesting to hear about let's it is i i could go for hours on this so be careful there

01:01:18 michael i find it really interesting that you just the extreme simplicity of like i've got a server

01:01:25 and either it's got a self-contained python and database runtime or it's just even a static site

01:01:31 that goes a long ways you know really long ways instead of like all the 100 connected services

01:01:36 powered by some dynamic thing underneath.

01:01:39 And if one of them goes down, it takes a chunk with it.

01:01:41 Yeah, yeah, for sure.

01:01:43 Maybe that was my last question.

01:01:44 I think just the deployment side of things is really interesting.

01:01:48 So it sounds like just wherever, right?

01:01:50 Anything that serves static files, you get to go.

01:01:52 Pretty much, yeah.

01:01:52 Because you get the site directory and you just go with that.

01:01:56 Like it's complete site in a directory.

01:01:57 Yeah, okay.

01:01:58 So the second, now I remember, the second thing I wanted to talk about was

01:02:01 if I go over to the user guide and I do a quick start,

01:02:04 You show me the structure and I get this here, this yourprojectgreatdocs.aml, greatdocs, et cetera, et cetera.

01:02:12 So it looks like the recommendation is to have great docs

01:02:16 as a sub directory of your actual things that it is documenting.

01:02:23 Is that right?

01:02:23 Sort of, but you don't have to keep it.

01:02:25 I mean, like it's just going to appear there when you render locally

01:02:29 and you can look at the site, you can preview it, but you can just delete it.

01:02:32 I can have it on CI or whatever, like on your CI system or however you're deploying.

01:02:36 Like your step could be build and then copy and then delete.

01:02:39 Yeah, exactly.

01:02:40 The folder, not necessarily the YAML.

01:02:43 Well, yeah, you want to keep that.

01:02:44 Yeah, yeah, that's config.

01:02:45 So that, commit that.

01:02:47 And hopefully I sort of like outlined it here on this page,

01:02:49 what should be like, you know, committed.

01:02:51 And we automatically .gitignore some things too.

01:02:52 So you don't accidentally commit things.

01:02:54 You don't have to.

01:02:54 If I want to do the freeze though, I probably have to keep it.

01:02:57 Yeah.

01:02:57 No, we actually work around that.

01:02:59 So we do like a, like a pre.

01:03:02 We got a little system there.

01:03:03 So I know it wipes everything out, but we have a freeze mechanism

01:03:05 that sort of works around this sort of like ephemeral nature of things.

01:03:09 Yeah, still uses coral freeze.

01:03:10 So it just does it a little bit different.

01:03:12 Yeah, very interesting.

01:03:13 Okay, final thoughts.

01:03:15 People are interested in this.

01:03:16 They want to get started.

01:03:17 What do you tell them?

01:03:18 Yeah, just check out the site.

01:03:19 I'm hoping you'll be not wowed, but that it will resonate a little bit

01:03:24 and the site should demonstrate what's possible.

01:03:28 And again, like, you know, Even just like have your agent,

01:03:32 like, you know, like have some AI, take a small Python package

01:03:36 of yours and see what it could do.

01:03:38 Take it for a little spin.

01:03:39 And if there's anything that you think is missing or lacking,

01:03:42 just drop me a line, like through the issues.

01:03:44 That's like, that's basically it.

01:03:46 Can I publish on read, read the docs?

01:03:48 I don't think we have that yet.

01:03:49 Yeah.

01:03:50 I actually never even considered that as a, as a publishing point.

01:03:54 One of the standard places to put docs, not necessarily required,

01:03:58 but it's, it'd be interesting, you know?

01:03:59 Okay.

01:04:00 I'm going to log that down.

01:04:01 That's already like, that's a good one.

01:04:02 All right. We're rewriting the roadmap live here.

01:04:05 Yeah.

01:04:06 That's a toughie.

01:04:07 You threw down the gauntlet, you know, this is it.

01:04:12 Sounds good.

01:04:13 Well, I really appreciate you both being here.

01:04:16 Michael, you want to have a final word as well of inspiration for folks?

01:04:19 What a great question.

01:04:20 I, my, my final nudge might be like, we talked a lot about generating docs, the kind of technical activity.

01:04:27 I do think there's this world of how do you write docs?

01:04:30 Like what should your content be?

01:04:32 And what should your sections of your doc site be?

01:04:34 Obviously we're saying goodbye.

01:04:36 So that's, we don't want to open that can of worms.

01:04:38 But I just wanted to cast a light on that.

01:04:41 That is a freaky big area on its own.

01:04:45 I don't have great answers.

01:04:47 So I'm just throwing some problems on people's laps.

01:04:49 But I think that's a neat freaky area that is worth checking out.

01:04:54 I think what you're doing is you're setting the stage for another episode in the future.

01:04:58 Yeah, that's right.

01:05:00 We're just trying to make it a three, you know,

01:05:03 like a trilogy.

01:05:04 So we're trying to get our third visit in.

01:05:07 Perfect.

01:05:08 All right.

01:05:08 Well, Rich, Michael,

01:05:09 thanks for being here.

01:05:10 It's great as always.

01:05:11 Thanks so much for having us.

01:05:12 Yeah.

01:05:12 Bye.

01:05:13 Thanks.

01:05:14 This has been another episode of Talk Python To Me.

01:05:17 Thank you to our sponsors.

01:05:18 Be sure to check out what they're offering.

01:05:19 It really helps support the show.

01:05:21 This episode is brought to you by Sentry.

01:05:24 You know Sentry for the error monitoring, but they now have logs too.

01:05:27 And with Sentry, your logs become way more usable,

01:05:30 interleaving into your error reports to enhance debugging and understanding.

01:05:35 Get started today at talkpython.fm/sentry.

01:05:39 And it's brought to you by Temporal, durable workflows for Python.

01:05:42 Write your workflows as normal Python code, and Temporal ensures they run reliably,

01:05:47 even across crashes and restarts.

01:05:50 Get started at talkpython.fm/Temporal.

01:05:53 If you or your team needs to learn Python, we have over 270 hours of beginner and advanced courses on topics ranging from complete beginners to async code, Flask, Django,

01:06:03 HTML, and even LLMs.

01:06:05 Best of all, there's no subscription in sight.

01:06:08 Browse the catalog at talkpython.fm.

01:06:11 And if you're not already subscribed to the show on your favorite podcast player,

01:06:14 what are you waiting for?

01:06:16 Just search for Python in your podcast player.

01:06:18 We should be right at the top.

01:06:19 If you enjoy that geeky rap song, you can download the full track.

01:06:22 The link is actually in your podcast below or share notes.

01:06:25 This is your host, Michael Kennedy.

01:06:26 Thank you so much for listening.

01:06:28 I really appreciate it.

01:06:29 I'll see you next time.

01:06:48 of getting old.

01:06:50 We tapped into that modern vibe overcame each storm.

01:06:55 Talk Python To Me.

01:06:56 I sync is the norm.

01:07:27 Продолжение следует...