Michael Kennedy: Your documentation has two audiences now,
Michael Kennedy: humans reading the rendered HTML and AI agents making
Michael Kennedy: sense of your library.
Michael Kennedy: Rich, I known,
Michael Kennedy: and Michael Chow from Posit are back on Talk Python with a
Michael Kennedy: brand new Python documentation tool called GreatDocs that takes both seriously.
Michael Kennedy: Rich is the creator of
Michael Kennedy: Great Tables and before that,
Michael Kennedy: the R package GT.
Michael Kennedy: The man has a serious eye for design and he's pointed
Michael Kennedy: that energy at the Python Docs ecosystem.
Michael Kennedy: We'll talk about how GreatDocs spins up a polished site
Michael Kennedy: and three commands,
Michael Kennedy: why every page ships as markdown for your favorite LLM,
Michael Kennedy: how it leans
Michael Kennedy: on corto for executable code blocks and tabbed install sections,
Michael Kennedy: and where it lands against
Michael Kennedy: Sphinx,
Michael Kennedy: MakeDocs,
Michael Kennedy: and Zensical.
Michael Kennedy: Plus,
Michael Kennedy: you'll meet Tablin. Here we go. This is Talk Python To Me,
Michael Kennedy: episode 549,
Michael Kennedy: recorded May 19th,
Michael Kennedy: 2026.
Michael Kennedy: Welcome to Talk Python To Me, the number one Python podcast for developers and data scientists.
Michael Kennedy: This is your host,
Michael Kennedy: Michael Kennedy.
Michael Kennedy: I'm a PSF fellow who's been coding for over 25 years.
Michael Kennedy: Let's connect on social media.
Michael Kennedy: You'll find me and Talk Python on Mastodon, Bluesky,
Michael Kennedy: and X.
Michael Kennedy: The social links are all in your show notes.
Michael Kennedy: You can find over 10 years of past episodes at talkpython.fm.
Michael Kennedy: And if you want to be part of the show, you can join our recording live streams.
Michael Kennedy: That's right.
Michael Kennedy: We live stream the raw uncut version of each episode on YouTube.
Michael Kennedy: Just visit talkpython.fm/youtube to see the schedule of upcoming events.
Michael Kennedy: Be sure to subscribe there and press the bell so you'll get notified anytime we're recording.
Michael Kennedy: Hey friends, before we dive in, I want to share something I just launched over at Talk Python,
Michael Kennedy: a new course.
Michael Kennedy: If you ship Python to production,
Michael Kennedy: you've probably had that quiet thought about
Michael Kennedy: what might be lurking in your code.
Michael Kennedy: My new course turns that worry into a concrete workflow
Michael Kennedy: and a reusable AI security agent that's yours forever.
Michael Kennedy: It's Python Web Security,
Michael Kennedy: the OWASP top 10 with agentic AI.
Michael Kennedy: Check it out at talkpython.fm/AI dash web dash security.
Michael Kennedy: The link is in your podcast player and on the episode page,
Michael Kennedy: or just go to talkpython.fm
Michael Kennedy: and click on courses at the top.
Michael Kennedy: It should be right there.
Michael Kennedy: So if you're interested in making sure the apps and APIs that you ship are secure,
Michael Kennedy: this
Michael Kennedy: is the course for you.
Michael Kennedy: This episode is brought to you by Sentry.
Michael Kennedy: You know Sentry for the error monitoring,
Michael Kennedy: but they now have logs too.
Michael Kennedy: And with Sentry,
Michael Kennedy: your logs become way more usable,
Michael Kennedy: interleaving into your error reports
Michael Kennedy: to enhance debugging and understanding.
Michael Kennedy: Get started today at talkpython.fm/sentry.
Michael Kennedy: And it's brought to you by Temporal,
Michael Kennedy: durable workflows for Python.
Michael Kennedy: Write your workflows as normal Python code and Temporal ensures they run reliably,
Michael Kennedy: even across crashes and restarts.
Michael Kennedy: Get started at talkpython.fm/Temporal.
Michael Kennedy: Rich, Michael,
Michael Kennedy: welcome back to Talk Python To Me.
Michael Kennedy: Awesome to have you both back on the show.
Michael Kennedy: Yeah, thanks for having us.
Michael Kennedy: We're going to talk about great things.
Michael Kennedy: I know it's going to be a great show.
Michael Kennedy: It's undoubtable,
Michael Kennedy: right?
Michael Chow: I have no doubt.
Michael Chow: It's a great day,
Michael Chow: you know,
Michael Chow: and we're ready for,
Michael Chow: I think what's going to be a
Michael Chow: great chat.
Michael Kennedy: Yeah.
Michael Kennedy: About great docs,
Michael Kennedy: great tables,
Michael Kennedy: all of those things.
Michael Kennedy: All the great things.
Michael Kennedy: Yeah.
Michael Kennedy: So I had you on to talk about great tables,
Michael Kennedy: which was really fun.
Michael Kennedy: You all both from Posit.
Michael Kennedy: And
Michael Kennedy: other than that, maybe let's do a quick introduction for folks.
Michael Kennedy: I mean, I don't know why anybody would
Michael Kennedy: not have listened to the great tables episode,
Michael Kennedy: but in case they haven't. No, we honestly,
Michael Kennedy: we get a bunch of new listeners all the time.
Michael Kennedy: So yeah, let's do a quick round of introductions.
Michael Kennedy: Who are you?
Michael Kennedy: What do you do? Why are you working on this project?
Michael Kennedy: Rich,
Michael Kennedy: start with you.
Rich lannone: Yeah.
Rich lannone: I'm Rich.
Rich lannone: I work at Posit,
Rich lannone: PBC.
Rich lannone: I've been doing traditionally lots of R stuff,
Rich lannone: like in the past,
Rich lannone: but more lately,
Rich lannone: this is like the last three or four years,
Rich lannone: a lot more Python
Rich lannone: stuff.
Rich lannone: And actually Michael,
Rich lannone: who's with me today,
Rich lannone: he taught me a lot about Python.
Rich lannone: Like I was
Rich lannone: pretty bad starting.
Rich lannone: I mean, I used in the past, but I was open source stuff. I was,
Rich lannone: oh that was bad michael has so much patience though so uh he'll make up speed over a period
Rich lannone: 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
Michael Kennedy: agree with that i think it's it's hard to change a language it's hard to switch to another language
Michael Kennedy: and maybe you could speak to that real quick before michael jumps in and just i've done that a couple
Michael Kennedy: times you know you spend so much time and energy and effort and getting really good at a not just
Michael Kennedy: the language,
Michael Kennedy: the tools, the ecosystem,
Michael Kennedy: everything.
Michael Kennedy: And then you're like, I'm one O, I think I have to go over there for a while.
Rich lannone: Yeah.
Rich lannone: It feels like a bizarro situation.
Rich lannone: Like I know what I could be doing,
Rich lannone: what should be doing,
Rich lannone: like theoretically,
Rich lannone: but things just
Rich lannone: don't jive sometimes.
Rich lannone: It's like, oh,
Rich lannone: yeah.
Rich lannone: But then you, then you get used to it and then your previous language degrades.
Rich lannone: It's kind of like that sort of thing.
Michael Kennedy: It's a little bit, a little bit sad in that regard, but you know, for me,
Michael Kennedy: the real challenge
Michael Kennedy: was I'm,
Michael Kennedy: I have such a deep knowledge and mastery of this technology.
Michael Kennedy: And if I switch,
Michael Kennedy: 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.
Michael Kennedy: And I was so hard for this knowledge and this experience.
Michael Kennedy: Why am I going to do this?
Michael Kennedy: Maybe I should never do that.
Michael Kennedy: It was really, it was a big deal for me.
Michael Kennedy: Maybe you could just,
Michael Kennedy: I want to say that for other people out there who are not necessarily going R to Python, but just one tech to another.
Rich lannone: Yeah, it's humbling,
Rich lannone: like I said.
Rich lannone: And well,
Rich lannone: you know,
Rich lannone: with a good venture and lots of patience,
Rich lannone: it can happen.
Michael Kennedy: Yeah, it's good to expand your skills,
Michael Kennedy: but the initial decision is rough.
Michael Kennedy: Michael,
Michael Kennedy: you've been shepherding Rich along the way.
Michael Kennedy: I love it.
Michael Kennedy: Tell us about yourself.
Michael Chow: I wouldn't even say shepherding, or maybe there's like some mutual shepherding going on.
Michael Chow: So I'm Michael Chow.
Michael Chow: I'm a software engineer at Posit and have been for about four years on the open source team.
Michael Chow: Yeah.
Michael Chow: And I,
Michael Chow: so I've worked with Rich on things like great tables.
Michael Chow: And I think that,
Michael Chow: yeah, I'm really interested in Python.
Michael Chow: I work on Python full time.
Michael Chow: I think if I had to send back what Rich is really good at,
Michael Chow: Rich just has this crazy,
Michael Chow: freaky sense of style.
Michael Chow: And I think that's one thing that's drawn me to work with him on things is you just never know.
Michael Chow: Like, to be totally honest,
Michael Chow: people at Posit just never know what Rich is going to pull out.
Michael Chow: And I don't think any of us could have imagined it.
Michael Chow: He's a loose,
Michael Chow: he's our wild card.
Michael Chow: And it's been interesting because you can imagine like a programming language.
Michael Chow: Yeah, you could be like, oh, this person taught me this programming language.
Michael Chow: I don't really know how you teach Rich's style,
Michael Chow: but I feel like I'm kind of along for the ride. I'm like eating popcorn,
Michael Chow: helping out. And I think tools like Great Docs really reflect that, this interesting sense of style.
Michael Chow: Great tables.
Michael Chow: He's just dipped into this rich history of table styling.
Michael Chow: How would you style it to present and maybe publish it?
Michael Chow: 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.
Michael Chow: Yeah,
Michael Kennedy: that's really cool.
Michael Kennedy: You know,
Michael Kennedy: certain people just have a knack for APIs and the way that develop,
Michael Kennedy: you know, the developer UX sort of thing.
Michael Kennedy: That's cool.
Michael Kennedy: I personally am excited for the mascot.
Michael Kennedy: Yeah,
Michael Kennedy: Rich,
Michael Chow: I blew your cover.
Michael Chow: we were yeah so michael and i were talking a little bit at pycon uh about uh tablin how you're
Michael Chow: tablin yes he hasn't been trying out a mascot wizard yeah who is tablin though i wonder he's
Rich lannone: just a little table guy a little table dude that appears gives you help and then disappears just
Michael Chow: as fast um right he hasn't fully realized he's he's he's always thinking of you he's never thinking
Michael Chow: of himself you know he's he's showing up helping you out he's like the new uh the bee or bob but
Rich lannone: much cooler because he's a table and can display things this absolutely yeah and i do think this
Michael Chow: speaks to our dynamic where tablin just appeared one day like well while we were preparing a pi
Michael Chow: con talk two years ago tablin just appeared in the slides and i didn't know who tablin was and i was
Michael Chow: like who or what is this it was like a slide of a table and tablin was popped out on the side was
Michael Chow: saying good job and i was like who's this spreadsheet with eyes and a mouth cheering
Michael Chow: people on and rich was like it's tablin of course yeah it's helpful to have a little dude that just
Rich lannone: wants to help you know it's like having a pet like a cat i love it it's really good so michael
Michael Kennedy: we had the great opportunity to meet up at pycon just last week i know i don't know how you feel
Michael Kennedy: about it personally i'm still just a little bit recovering from the whole energy that was extracted
Michael Kennedy: from me you know but it was really fun and maybe just give us your thoughts on pycon and how'd that
Michael Kennedy: go.
Michael Chow: Yeah.
Michael Chow: Yeah. It's a great question.
Michael Chow: I,
Michael Chow: um,
Michael Chow: it's so interesting because we work on tools for
Michael Chow: data analysis,
Michael Chow: but PyCon is much more general. It's almost like all things Python.
Michael Chow: I think it's
Michael Chow: a really interesting conference versus like a PyData or a SciPy, which are way oriented towards
Michael Chow: like data tools specifically.
Michael Chow: Um,
Michael Chow: but I love it. I find it really nice to be able to drop in and
Michael Chow: talk to just the full range of Python people who maybe have never used or done a lot of data
Michael Chow: So I find it really interesting to talk to folks who maybe almost universally, I think
Michael Chow: everybody has touched pandas, the library for data frames.
Michael Chow: And so that's the like funny kind of like point you can always talk to anyone about at
Michael Chow: PyCon,
Michael Chow: but I find it really nice.
Michael Chow: And I find the like PyCon organizers and the sort of Python software foundation,
Michael Chow: it's just
Michael Chow: so down to earth that,
Michael Chow: yeah, I really love dropping in.
Michael Chow: It doesn't feel super corporate.
Michael Chow: It feels like they're really like a group of passionate volunteers putting this like pretty big conference on.
Michael Chow: So,
Michael Chow: yeah,
Michael Chow: I always love dropping in,
Michael Chow: even if it's like a kind of broader audience than the like data crew.
Michael Chow: I'm curious your experience.
Michael Chow: Have you gone to a lot of PyCons?
Michael Kennedy: I think my first one,
Michael Kennedy: when was my first?
Michael Kennedy: Mid-teens,
Michael Kennedy: I would say 2015,
Michael Kennedy: 2016,
Michael Kennedy: something like that.
Michael Kennedy: Yeah,
Michael Kennedy: nice.
Michael Kennedy: I'd probably have gone to maybe two thirds since then.
Michael Kennedy: Most.
Michael Kennedy: I mean, we did have COVID in the middle.
Michael Kennedy: That was challenging.
Michael Kennedy: But yeah,
Michael Kennedy: I've been to a fair number and I really enjoy it.
Michael Kennedy: And for me, it's just nice to get together,
Michael Kennedy: meet folks like you and everyone else and
Michael Kennedy: just kind of remember,
Michael Kennedy: hey, this is a community of humans and not just docs.
Michael Kennedy: Never mind.
Michael Kennedy: I mean,
Michael Kennedy: docs are great.
Michael Kennedy: We're going to talk about how great docs can be.
Michael Kennedy: But it's also nice to just have these human connections and just connect with people outside
Michael Kennedy: of with,
Michael Kennedy: but also outside of technology,
Michael Kennedy: right?
Michael Kennedy: Like,
Michael Kennedy: let's just go sit in the sun for a while and talk.
Michael Kennedy: Like, have you seen The Sun lately?
Michael Kennedy: No, I haven't seen it either.
Michael Kennedy: Let's go sit there.
Michael Chow: All day.
Michael Chow: Yeah.
Michael Chow: Yeah, for real.
Michael Chow: I feel like it is.
Michael Chow: Just putting the face behind the name or actually like touching down to chat does seem like
Michael Chow: a huge thing that you only do like say once or twice a year.
Michael Chow: Yeah.
Michael Kennedy: With those folks.
Michael Kennedy: Yeah.
Michael Kennedy: At least for me, I can come back and revitalize to do more.
Michael Kennedy: So that's really, really sweet.
Michael Kennedy: Let's start our journey here.
Michael Kennedy: Talking about, just do a quick review of Great Tables.
Michael Kennedy: Because I know Great Tables was one of the inspirations for Great Docs.
Michael Kennedy: So we all both got together,
Michael Kennedy: all three of us got together last year,
Michael Kennedy: I guess,
Michael Kennedy: to talk about Great Tables.
Michael Kennedy: So who wants to just do a quick reminder of this one?
Rich lannone: I'll go.
Rich lannone: So basically,
Rich lannone: yeah, Great Tables,
Rich lannone: it's a,
Rich lannone: maybe not many people know this,
Rich lannone: it's a port of an R package called GT.
Rich lannone: Not that important, but the idea is good as it was then.
Rich lannone: You want display tables,
Rich lannone: what I call them.
Rich lannone: essentially summary tables like static tables and you want to present them say in a notebook or say
Rich lannone: like in some other publishable document as html we also have a latex output format but the idea is
Rich lannone: you compose tables step by step you know you add a header you want you want a title you get that too
Rich lannone: you structure the table you can format different cells like usually entire columns of cells or and
Rich lannone: you can also style a table which could be like you know like changing orders adding cell backgrounds
Rich lannone: things like that.
Rich lannone: And really the idea is to like to make a table that you might see like in a print
Rich lannone: publication,
Rich lannone: but using your data,
Rich lannone: like directly,
Rich lannone: like using a data frame.
Rich lannone: So you have the data in
Rich lannone: a form which is amenable to a summary table.
Rich lannone: And then in just a few like method calls,
Rich lannone: you've got
Rich lannone: the table.
Michael Kennedy: Yeah,
Michael Kennedy: that's awesome.
Michael Kennedy: What strikes me about this,
Michael Kennedy: when we had our conversation last year,
Michael Kennedy: It's just how much more there is to think about with tables than, you know, just an Excel-like thing.
Michael Kennedy: I came away realizing that it goes way deeper and there's a lot more nuance.
Michael Kennedy: 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.
Michael Kennedy: But it's...
Michael Kennedy: Is it Stephen Peavy?
Michael Kennedy: Tufty?
Michael Kennedy: No,
Michael Kennedy: no, no.
Michael Kennedy: Tufty.
Michael Kennedy: Tufty, yes.
Michael Kennedy: Okay.
Michael Kennedy: He's just like, oh,
Michael Kennedy: I see.
Michael Kennedy: Like there's some lines and stuff like, no, no, no, no.
Michael Kennedy: Hold on.
Michael Kennedy: There's a lot going on.
Michael Kennedy: And like,
Michael Kennedy: there's many things you can communicate subtly without just being like, well, let's just call this out.
Michael Kennedy: Like, no, you don't even have to call it out.
Michael Kennedy: It's communicated through something more interesting.
Michael Kennedy: You know, a tough thing is that about just presenting sort of scientific information in general.
Michael Kennedy: But I felt that way about tables as well.
Rich lannone: Yeah, it's pretty well.
Rich lannone: We talked about this in our talk a few years back in PyCon.
Rich lannone: how like you can tell a story with a table where you can communicate data in a better way in a
Rich lannone: not a more optimized way but a more legible way where like your main point is like describe like
Rich lannone: a title and a subtitle and you have notes at the bottom and you can guide people through an analysis
Rich lannone: summary that way and so just like with many different things there's a good way to do it
Michael Kennedy: or a better way to do it yeah there's you could just look at certain types of presented information
Michael Kennedy: and you go,
Michael Kennedy: well, that looks really professional
Michael Kennedy: or that looks really,
Michael Kennedy: really good,
Michael Kennedy: but I don't know why.
Michael Kennedy: You know what I mean?
Michael Kennedy: Yeah.
Michael Kennedy: This looks bad.
Michael Kennedy: That was good, but I don't, yes,
Michael Kennedy: but I can't put my hand or my finger
Michael Kennedy: on exactly what is really different,
Michael Kennedy: but that's really good and that's not, you know?
Michael Kennedy: And I feel like Great Tables kind of leans into that.
Rich lannone: Yeah, I guess it takes the Tufti principle too,
Rich lannone: like having just the right amount of ink,
Rich lannone: I guess,
Rich lannone: like not too much,
Rich lannone: just enough to communicate
Rich lannone: the structure of things,
Rich lannone: like the sort of like the architecture of the data you're laying out and not doing much more than that.
Rich lannone: So there's a lot of that that goes into this.
Michael Chow: Indeed.
Rich lannone: As a default thing.
Michael Chow: To the Tufti point too,
Michael Chow: Tufti's website,
Michael Chow: Tufti has like all of these just dumps of examples,
Michael Chow: just like example plot,
Michael Chow: example plot, example plot.
Michael Chow: It's almost like a very rough notebook.
Michael Chow: And I feel like with great tables,
Michael Chow: it was kind of similar.
Michael Chow: Like when I first came on, I knew basically nothing about this topic.
Michael Chow: And I saw the components of the table diagram.
Michael Chow: So you have it pulled up,
Michael Chow: but it has like a table broken apart into all its pieces,
Michael Chow: like
Michael Chow: a title,
Michael Chow: subtitle.
Michael Chow: There's this funny thing called the stub head and spanners.
Michael Chow: And I thought like,
Michael Chow: does a person really need to know all this?
Michael Chow: But I think to the point of Tufti, like maybe what you're getting out to is Tufti really
Michael Chow: dives into like very specific,
Michael Chow: almost like dimensions of how you could represent data.
Michael Chow: One thing he gets really into is like sparklines,
Michael Chow: this idea that like how far could you get with a line that basically doesn't have any axis labels,
Michael Chow: but it's just like a trend.
Michael Chow: Like is it going up or is it going down?
Michael Chow: And that happens a lot in tables.
Michael Chow: You'll put like these sparklines in a cell.
Michael Chow: Like if you're looking at stocks,
Michael Chow: 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.
Michael Chow: But I find what's interesting about Tufti is just that willingness to dive in so detailed about this one very specific action.
Michael Chow: And I feel like this table diagram is sort of similar to me,
Michael Chow: the willingness to break it apart so thoroughly.
Michael Chow: At first, I wasn't really convinced.
Michael Chow: It seemed like a lot of work.
Michael Chow: But yeah, I think to your point about Tufti,
Michael Chow: 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.
Rich lannone: Yeah,
Rich lannone: I think it's really out there.
Rich lannone: Like initially when I did too, it was like, oh, this is too much.
Rich lannone: But naming things is so important.
Rich lannone: Otherwise, you're just awkwardly describing something over and over again,
Rich lannone: like that cell
Rich lannone: to the top left or these cells off to the side.
Rich lannone: And eventually you just have to give it a name,
Rich lannone: even if it's not the best name.
Rich lannone: And these are actually names I stole from like basically a census manual on tables,
Rich lannone: I think written in 1949.
Rich lannone: Great ideas,
Rich lannone: like wonderful book.
Rich lannone: And it's on the web as a PDF still.
Rich lannone: It's a scam.
Michael Kennedy: I remember I was talking about that.
Michael Kennedy: Yeah.
Michael Kennedy: How interesting is it?
Michael Kennedy: Yeah.
Michael Kennedy: How interesting is it that the inspiration comes from pre-digital times?
Michael Kennedy: Yeah.
Michael Kennedy: And I think that,
Michael Kennedy: yeah,
Michael Kennedy: because a lot of the software reduces some of these ideas.
Michael Kennedy: It's like, well, I have grids.
Michael Kennedy: I have a grid of cells and sometimes the rows can be taller.
Michael Kennedy: Sometimes you can span a row.
Michael Kennedy: Okay.
Michael Kennedy: That's that.
Michael Kennedy: But if you just write it by hand when you have to way back in the day,
Michael Kennedy: it's like, oh,
Michael Kennedy: well,
Michael Kennedy: maybe we could draw it differently,
Michael Kennedy: right?
Rich lannone: Yeah.
Rich lannone: And it's like, I was like searching,
Rich lannone: like researching,
Rich lannone: like anything on tables I could find
Rich lannone: just to get ideas and like, you know,
Rich lannone: like what people thought was good.
Rich lannone: And it's really hard to find anything on tables.
Rich lannone: It was like, oh, but I did find that one thing.
Rich lannone: And like,
Rich lannone: I'm forever in debt to the person who wrote it.
Michael Kennedy: Yeah, that's awesome.
Michael Kennedy: This portion of Talk Python To Me
Michael Kennedy: is brought to you by Sentry.
Michael Kennedy: You know Sentry for their great error monitoring,
Michael Kennedy: but let's talk about logs.
Michael Kennedy: Logs are messy.
Michael Kennedy: Trying to grep through them and line them up
Michael Kennedy: with traces and dashboards just to understand one issue
Michael Kennedy: isn't easy.
Michael Kennedy: Did you know that Sentry has logs too?
Michael Kennedy: And your logs just became way more usable.
Michael Kennedy: Sentry's logs are trace connected and structured,
Michael Kennedy: so you can follow the request flow and filter by
Michael Kennedy: what matters.
Michael Kennedy: And because Sentry surfaces the context right where you're debugging,
Michael Kennedy: the trace relevant logs,
Michael Kennedy: the error,
Michael Kennedy: and even the session replay all land in one timeline.
Michael Kennedy: No timestamp matching,
Michael Kennedy: no tool hopping.
Michael Kennedy: From front end to mobile to back end,
Michael Kennedy: whatever you're debugging,
Michael Kennedy: Sentry gives you the context you need so you can fix
Michael Kennedy: the problem and move on.
Michael Kennedy: More than 4.5 million developers use Sentry,
Michael Kennedy: including teams at
Michael Kennedy: Anthropic and Disney+. Get started with Sentry logs and error monitoring today at talkpython.fm
Michael Kennedy: slash Sentry.
Michael Kennedy: Be sure to use our code, talkpython26.
Michael Kennedy: The link is in your podcast player show notes.
Michael Kennedy: Thank you to Sentry for supporting the show.
Michael Kennedy: Let's move on, but if people are out there and
Michael Kennedy: they're doing presentations that involve tables,
Michael Kennedy: and especially if it's code generating those
Michael Kennedy: tables.
Michael Kennedy: Check this out.
Michael Kennedy: It's quite interesting.
Michael Kennedy: So the next thing I want to talk about is just
Michael Kennedy: sort of surveying the landscape of what is out there,
Michael Kennedy: because we're going to talk about great
Michael Kennedy: docs and great docs can generate static sites.
Michael Kennedy: So there's some existing tools that generate docs
Michael Kennedy: as static site. There's some really good tools that just generate static sites that maybe people
Michael Kennedy: could put into docs. Like there's a lot of things that are somewhat similar.
Michael Kennedy: There's also stuff
Michael Kennedy: that's in the same space, but different. So maybe we could kind of go through and,
Michael Kennedy: you know, like
Michael Kennedy: I know you all have mentioned Sphinx is a real popular one in the Python space.
Michael Kennedy: There's MKDocs.
Michael Kennedy: I had Martin from Zensical on not too long ago.
Michael Kennedy: So maybe we could talk first about some of the existing tools that are,
Michael Kennedy: I guess, as similar as possible to what you're doing.
Rich lannone: Yeah.
Rich lannone: Michael, would you like to speak on this?
Rich lannone: Because I know you did a deep dive recently on these.
Michael Chow: Yeah.
Michael Chow: So Sphinx,
Michael Chow: I think,
Michael Chow: and maybe to kick off some helpful context to great docs is that, yeah,
Michael Chow: I worked a lot on early support for documentation with a tool called QuarterDoc.
Michael Chow: But Rich actually took it to the next level.
Michael Chow: And this goes to, I think, Rich's style with great docs.
Michael Chow: So I have a lot of bizarre experience looking at the history of Python docs.
Michael Chow: I think Sphinx is one of the OG site builders.
Michael Chow: I think this is the case.
Michael Chow: So I think one interesting fact is, as I understand it, I think Python.org,
Michael Chow: don't quote me on this.
Michael Chow: I think it was originally done in like LaTeX or something like that,
Michael Chow: the Python docs.
Michael Chow: And I think that they moved to Sphinx at some point.
Michael Chow: So like Sphinx has a really interesting history in Python.
Michael Chow: Like if you go back 25,
Michael Chow: 30 years,
Michael Chow: Python docs had to exist using some tool,
Michael Chow: right?
Michael Chow: And at some point Sphinx emerged as kind of like this dominant site builder for Python and Python docs.
Michael Chow: Yeah, does it say?
Michael Chow: Yeah.
Michael Chow: So Python docs are in Sphinx.
Michael Chow: you know this python doc site has a how-to python how-tos this is another weird fact
Michael Chow: the how-tos emerged I don't remember exactly when they emerged it was like in the last 30 years I
Michael Chow: think as part of the Linux project so the term how-to as I understand it emerged in the Linux
Michael Chow: docs but all these things like it's so funny we see them today and and maybe it seems we just
Michael Chow: think about like,
Michael Chow: oh,
Michael Chow: there's the Python docs,
Michael Chow: but actually at a certain point,
Michael Chow: you know,
Michael Chow: Sphinx
Michael Chow: emerged,
Michael Chow: this concept of a how-to emerge.
Michael Chow: These are all things that over the last, I think like
Michael Chow: 30 years sort of like came into existence.
Michael Chow: So Sphinx is like the OG doc site.
Michael Chow: A lot of tools
Michael Chow: use it.
Michael Chow: Pandas uses it to generate its APIs.
Michael Chow: Polars uses it as well.
Michael Chow: So some really big
Michael Chow: python tools use it to generate their um api docs um it uses this thing called restructured text
Michael Chow: 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
Michael Chow: a bit careful here because i think it's been so useful but i do think that restructured text is
Michael Chow: kind of not the thing most open source developers are reaching for these days um but sphinx is like
Michael Chow: the og uh doc site and it powers a ton of docs like python.org and pandas i'm sure if you know
Michael Kennedy: i'm sure it was really made a huge improvement when it came out though right yeah i think if
Michael Chow: you're doing a look at before that's got to be yeah yeah it's like zero to one essentially i think
Michael Chow: switching from lit tech to sphinx for like your python docs yeah and if i see an rst file it's
Michael Kennedy: 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
Michael Chow: passage i feel like as a python developer producing docs in the like sphinx world you just
Michael Chow: kind of like you learn i learned sphinx and rst to generate docs essentially uh it's like yeah i
Michael Chow: feel like that was my rite of passage into like software development 100 so we've also got mk docs
Michael Chow: 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
Michael Chow: you had the zensical people so i feel like they do you have a read on it if i try to remember i
Michael Kennedy: like martin said mk docs but whoa i i not he could have easily said make docs and i was not paying
Michael Kennedy: attention yeah um i'm a doctor so yeah no i think that i think that makes sense a lot of these that
Michael Kennedy: could be said one way or another i really wish and maybe this does but i really wish on their
Michael Kennedy: github repo they just have a little mp3 like here's how you say it you know what i mean
Michael Kennedy: little audio button yeah exactly it's like a green unicorn like g unicorn versus goonicorn is
Michael Kennedy: like a one that i think goes around and around still yeah okay so zensical is um one of the more
Michael Kennedy: modern ones so i think that that's pretty interesting i don't honestly i'm not sure how
Michael Kennedy: much it lands in the sphinx mcdocs world or in the other maybe the just pure static site generator
Michael Chow: side of things i mean the sensical folks came on and probably have the best sense but um my sense
Michael Chow: is it's also meant to be kind of a i might be wrong drop-in replacement for make docs i know
Michael Kennedy: their community yeah yeah it is a it is a um compatibility at least compatible uh for a material
Michael Kennedy: for make docs yeah right right right yeah for sure so yeah i would say it's in that in that realm
Rich lannone: it also seems like they're heading towards general purpose or knowledge bases which goes
Michael Kennedy: maybe a bit beyond just like yes exactly that was my like uncertainty is how do i classify it right
Michael Kennedy: because it's it doesn't even necessarily if you look at their h2 it doesn't say the best way to
Michael Kennedy: make your docs right it's it's a scalable way for technical writing right which makes it i think
Michael Kennedy: land a little more in the hugo or ghost side of um thing so that's another part to part to talk
Michael Kennedy: about it's just like static sites in general you know why would i choose say sphinx over hugo or
Michael Kennedy: hugo over sphinx or something like that you guys got yeah it seems a bit like mitlefy they have the
Rich lannone: same sort of thing going to they do documentation sites but they go a bit beyond it's like general
Rich lannone: purpose lots of different languages supported uh but it is documentation but not really so much
Michael Kennedy: like a site like just general purpose site generator so it's so hugo and ghost i don't know
Michael Kennedy: goes very well,
Michael Kennedy: but Hugo,
Michael Kennedy: for example, I use that a lot for blogs. I've seen one of my friends does
Michael Kennedy: really cool stuff just in general with Hugo making general purpose sites.
Michael Kennedy: I feel like this is much
Michael Kennedy: more focused on,
Michael Kennedy: I just need a static site and much less, I need it to read my doc strings and
Michael Kennedy: categorize my modules and, and API calls and put in that kind of stuff. Right. So that's another,
Michael Kennedy: another realm that is similar to what you all are doing, but certainly not the same.
Rich lannone: Yeah,
Rich lannone: if you want to throw another one in, there's Korto by the company we work at, Posit,
Rich lannone: and that does sites and much more beyond.
Michael Kennedy: I do think I had JJ on and I'm so sorry, I'm forgetting the name of the other guy.
Michael Kennedy: Oh,
Michael Kennedy: Charles.
Michael Kennedy: Yeah, I think it was Charles.
Michael Kennedy: Oh,
Michael Kennedy: cool.
Michael Kennedy: To talk about Korto a little while ago.
Michael Kennedy: That was fun.
Michael Chow: Yeah.
Michael Chow: I do think a lot of the questions with like Hugo versus something more targeted at like docs for a
Michael Chow: tool is hitting on kind of like,
Michael Chow: what are the parts of a doc site?
Michael Chow: You know, like what's technical
Michael Chow: writing versus like package documentation?
Michael Chow: Am I just doing a Hugo thing? Like is what I'm doing
Michael Chow: similar enough to like a blog or a website with content,
Michael Chow: which is really common, like my website's
Michael Chow: in Hugo?
Michael Chow: Or do I need something special to like dump out my like API docs to dump out the things
Michael Chow: from my like functions and classes?
Michael Chow: Or could I jam that into Hugo?
Michael Chow: That's a common kind of hybrid
Michael Chow: path.
Michael Chow: Could my thing just dump my info into Hugo?
Michael Chow: It's all kind of this dance between really,
Michael Chow: is this a general content problem?
Michael Chow: Is this a like very specific tool problem?
Michael Chow: Or can I kind of like
Michael Chow: jam them both together into something.
Michael Kennedy: Yeah, that's an interesting problem.
Michael Kennedy: So maybe a good time to start talking about, you know, great docs.
Michael Kennedy: What is it?
Michael Kennedy: Like, what's its value prop and positioning with regard to these other areas?
Rich lannone: Well, on your screen, you have package down.
Rich lannone: Yes.
Rich lannone: It has an origin.
Rich lannone: Actually,
Rich lannone: coming from R,
Rich lannone: I can't help but to be a little bit influenced by package down.
Rich lannone: I use it a lot in my R projects.
Rich lannone: And I kind of felt like there was like a package downsized hole in the Python docs ecosystem,
Rich lannone: just a little bit, where, you know, you can just point something at your docs and it makes
Rich lannone: something pretty fast with pretty much no configuration.
Rich lannone: That's like the challenge.
Rich lannone: Does it present something that's serviceable,
Rich lannone: like usable right away?
Rich lannone: And that's what I was shooting for.
Rich lannone: And I think that's kind of like where I landed.
Rich lannone: And of course, we have tons of options to do way more things.
Rich lannone: But I wanted to give something that was,
Rich lannone: you know,
Rich lannone: you just start it right away and it gives
Rich lannone: you something.
Rich lannone: Like, for instance,
Rich lannone: you have doc strings and such,
Rich lannone: and they all just get captured and put into the API reference section.
Rich lannone: And then later on, you would, you know, attend to it and organize it and then, you know, arrange it and exclude things.
Rich lannone: At the very beginning, it would just give you something at least.
Rich lannone: So that was kind of like my goal.
Michael Kennedy: The up and running super quick is one of the themes,
Michael Kennedy: right?
Rich lannone: Yeah,
Rich lannone: yeah,
Rich lannone: absolutely.
Rich lannone: Because I think,
Rich lannone: I suspect,
Rich lannone: maybe a lot of people are getting more into Python now because of agents, AI, LLMs,
Rich lannone: and such,
Rich lannone: and are spinning up small projects.
Rich lannone: And maybe they're even building their documentation sites with using the same things, like LLMs.
Rich lannone: So getting something up quickly.
Rich lannone: And maybe the project doesn't last very long.
Rich lannone: It's just like something just to get going.
Rich lannone: And you don't want to spend a ton of time on learning the docs,
Rich lannone: a new doc system.
Rich lannone: So this sort of thing is pretty valuable.
Rich lannone: But we still give you the opportunity,
Rich lannone: of course, to,
Rich lannone: you know, like add things and do really
Rich lannone: cool,
Rich lannone: sophisticated sites.
Rich lannone: But just the up and running part, it was super important to me.
Michael Kennedy: So by default,
Michael Kennedy: you can point it at a package or set of Python files or something and say,
Michael Kennedy: generate docs around that.
Michael Kennedy: And it will look for doc strings and so on, and then generate some kind of hierarchical.
Rich lannone: Yeah, exactly.
Rich lannone: And we tested it quite a bit on different package layouts,
Rich lannone: like,
Rich lannone: you know, different
Rich lannone: packaging systems.
Rich lannone: And it seems introspect pretty well based on all sorts of variation.
Rich lannone: and we do test this a lot.
Rich lannone: So the promise is that it does give you something.
Michael Kennedy: And you can also create
Michael Kennedy: just more static site type stuff as well, yeah?
Rich lannone: Yeah, oh, absolutely,
Rich lannone: yeah,
Rich lannone: you can.
Michael Chow: I think the user guide's a good example.
Michael Chow: Like if you click the expandable thing in the top left.
Michael Kennedy: Yeah, everything's so zoomed.
Michael Kennedy: Yeah, everything's so zoomed
Michael Kennedy: on my little small streaming screen.
Michael Kennedy: So yeah,
Michael Kennedy: the user guide got it.
Michael Chow: It's nice, the user guide's just a folder
Michael Chow: in the repo with files in it.
Michael Chow: But it's nice like that that puts up this like,
Michael Chow: yeah,
Michael Chow: more kind of general bit of content where it's not your API reference,
Michael Chow: which is like each individual function explained,
Michael Chow: but a more general kind of guide,
Michael Chow: kind of like a bigger,
Michael Chow: higher level,
Michael Chow: like introduction to the package.
Michael Chow: But it's nice that to your point,
Michael Chow: like,
Michael Chow: can you have more general kind of content?
Michael Chow: It's nice.
Michael Chow: This is just a folder in the repo.
Michael Chow: So getting started with the user guides,
Michael Chow: like super fast.
Rich lannone: Yeah.
Rich lannone: And this site is like a demonstration.
Rich lannone: We're showing like the great docs site and we're just looking at it and you can just
Rich lannone: add another directory and like recipes at the top nav.
Rich lannone: That's just another directory.
Rich lannone: And we sort of declared it in our configuration file.
Rich lannone: So you can just create something similar to a user guide.
Rich lannone: But we sort of treat a user guide as a sort of like a first class thing because we,
Rich lannone: well, I'm a little bit opinionated about how sites,
Rich lannone: these doc sites should be.
Rich lannone: So it kind of serves as a model.
Rich lannone: So like the idea is that if someone sees this and says,
Rich lannone: yeah, I would like something like this,
Rich lannone: then like three docs would be a good fit.
Rich lannone: You just have sort of emulate what we have here,
Rich lannone: do a few things and you've pretty much got it beyond the simple sort of like init and then like build.
Rich lannone: We can just go a little bit beyond.
Michael Kennedy: Yeah,
Michael Kennedy: sitting here talking to you makes me think, you know, I've got some open source projects.
Michael Kennedy: I really should have better docs with him.
Rich lannone: Maybe.
Michael Kennedy: Maybe I'll try working on them with great docs.
Michael Kennedy: That would be really fun.
Michael Kennedy: Oh, yeah.
Rich lannone: And I love your feedback.
Rich lannone: I'm always looking for ideas and feedback.
Rich lannone: Right now,
Rich lannone: I'm not going to make a big deal of it.
Rich lannone: But I'm looking for users because this is a brand new project.
Rich lannone: So feedback is a bit scant at this point.
Rich lannone: So yeah,
Rich lannone: let me know how it goes.
Michael Kennedy: Yeah, I will definitely.
Michael Kennedy: One of the things that's nice here that I'm noticing is it's got a lot of elements of the
Michael Kennedy: display that go beyond just standard markdown that i think are really nice like for example
Michael Kennedy: you've got these oh because these are probably like little tags or badges yeah yeah and then
Michael Kennedy: also you've got a tabbed ui for like here's how you install it on mac Linux windows but in the
Michael Kennedy: same little area right you just like click the tab for your os yeah because tab sets in cordo
Rich lannone: they're like a cordo special really they just come part and parcel with cordo yeah yeah i feel like
Michael Kennedy: you can do some nice authorship beyond that.
Michael Kennedy: Like when I was working on my book,
Michael Kennedy: I'm like,
Michael Kennedy: I'm going to write it in Markdown,
Michael Kennedy: but I also want to have these little call outs
Michael Kennedy: or like an action or,
Michael Kennedy: you know, the little sidebar,
Michael Kennedy: like how in the heck am I going to get that
Michael Kennedy: to come out of Pandoc?
Michael Kennedy: You know what I mean?
Michael Kennedy: Yeah.
Michael Kennedy: I eventually got it to work by basically
Michael Kennedy: getting a little pre-parser
Michael Kennedy: that would just turn those into HTML
Michael Kennedy: and allow the Markdown to have HTML.
Rich lannone: I think that's what makes a good user guide
Rich lannone: a good user guide.
Rich lannone: We actually show,
Rich lannone: like, not just like show the code,
Rich lannone: but actually show the results.
Rich lannone: And you can totally do that with a good user guide.
Rich lannone: And that's what I try to demonstrate here
Rich lannone: in the Great Docs user guide
Rich lannone: that we have these things.
Rich lannone: Here's how they look.
Rich lannone: You can have these too.
Michael Chow: Yeah, that definitely looks good.
Michael Chow: That's the one thing too with Quarto
Michael Chow: that if I had to make the case for Quarto
Michael Chow: for a lot of people doing documentation,
Michael Chow: it's that it's really easy to run code.
Michael Chow: Running code is kind of like most of Quarto's game.
Michael Chow: It's a you author using a QMD.
Michael Chow: It's essentially a markdown file,
Michael Chow: but your code blocks can be executed.
Michael Chow: So it's really inconvenient for docs,
Michael Chow: like being able to include code snippets with their out and then they get run and their outputs are there.
Michael Chow: So that's kind of the impetus,
Michael Chow: I think, in this case for Bordeaux is doing like really easy execution of code.
Michael Chow: It's possible in other tools.
Michael Chow: And I know MakeDockstrings,
Michael Chow: who I think its author is working with Zensical now too.
Michael Chow: But they've created a lot of good ways for you to be able to do this as well, like execute code.
Michael Chow: But I do think that's one area where people stub their toe a lot is like,
Michael Chow: oh,
Michael Chow: like if I'm Polars or Pandas, I'm a data frame library.
Michael Chow: I probably want a lot of examples.
Michael Chow: And then you get stuck in this like funny dance, like how do I execute the code for my examples?
Michael Chow: And so I think tools like Quarto are really kind of aimed at that.
Michael Chow: use case like you're a person running code and generating reports you know that that have code
Rich lannone: and that produce graphs and tables and yeah and i think the examples like being executable made the
Rich lannone: great tables examples really powerful you can see the code for a table and then see the table
Rich lannone: right below like in the actual like site which is we didn't have to paste that in it was basically
Rich lannone: just generated right there yeah that's amazing which is actually incredibly you can put pros
Rich lannone: around it as well so it's like it reads just like a little mini guide in each doc string does it
Michael Kennedy: run at build time or does it somehow run in the website oh build time yeah yeah yeah you guys
Michael Kennedy: embedding WebAssembly or something fun like that no you could do that you could do that yeah i
Michael Chow: another nice thing you can freeze it so like if you have a bit of code that um or like let's say
Michael Chow: you have a blog post and you don't want to rerun it every time because like over the years maybe
Michael Chow: you like know the code's going to get out of date or it takes a long time to run.
Michael Chow: You can do
Michael Chow: something called freeze.
Michael Chow: You can quarter freeze it.
Michael Chow: And that essentially like caches the outputs
Michael Chow: so that you can re-render it without executing the code every time.
Michael Chow: So that's useful.
Michael Chow: Like
Michael Chow: great tables, we have kind of a growing log of blog posts and we don't want to re-execute them
Michael Chow: every time because that starts to get pretty time consuming.
Michael Chow: So we can just freeze their outputs
Michael Chow: and then they generate super fast.
Michael Kennedy: Another reason you might want to freeze it
Michael Kennedy: is you're doing accessing live data
Michael Kennedy: off an API or website
Michael Kennedy: and you want to talk about the results.
Michael Kennedy: And if it changes,
Michael Kennedy: like all of a sudden your pros is like,
Michael Kennedy: why are you talking about this?
Michael Kennedy: It doesn't say that.
Michael Kennedy: Well, it used to when I did it.
Michael Kennedy: You might imagine like a benchmark section example
Rich lannone: if it runs a long time
Rich lannone: or you just,
Rich lannone: you know,
Rich lannone: accessing some keys on your personal machine.
Rich lannone: Absolutely.
Rich lannone: Freezing is great for that.
Rich lannone: You basically froze stuff on your personal computer
Rich lannone: and you're just like,
Rich lannone: you know,
Rich lannone: sending it off to like CI.
Rich lannone: high.
Michael Chow: And I think there's like a million,
Michael Chow: there's also like a million of these things that you
Michael Chow: encounter when you start generating doc sites or like personal content,
Michael Chow: which is like,
Michael Chow: yeah,
Michael Chow: maybe I don't want to run some stuff.
Michael Chow: Maybe I want to like include a snippet from one thing
Michael Chow: somewhere else,
Michael Chow: or maybe I want to do like all kinds of like output customization.
Michael Chow: I just feel
Michael Chow: like there's a million little boxes to check.
Michael Chow: So that's, that's one.
Michael Chow: I mean,
Michael Chow: one other reason we
Michael Chow: use Kordo is we belong to the company that created Kordo.
Michael Chow: But I think those like little
Michael Chow: pieces of detail for people generating like scientific documents and stuff goes a long way.
Rich lannone: It's pretty wild too, because Kordo has a pretty big extension system as well,
Rich lannone: like pretty active.
Rich lannone: So there's like ways,
Rich lannone: I mean, besides like different output types,
Rich lannone: there's like extensions,
Rich lannone: and different types of extensions too,
Rich lannone: like different classes of extensions.
Michael Kennedy: So it goes really deep.
Michael Kennedy: Yeah,
Michael Kennedy: Quarto is really neat.
Michael Kennedy: This portion of Talk Python To Me is sponsored by Temporal.
Michael Kennedy: Ever since I had Mason Egger on the podcast for episode 515,
Michael Kennedy: I've been fascinated with durable workflows in Python.
Michael Kennedy: That's why I'm thrilled that Temporal has decided
Michael Kennedy: to become a podcast sponsor since that episode.
Michael Kennedy: If you've built background jobs or multi-step workflows,
Michael Kennedy: you know how messy things get with retries, timeouts,
Michael Kennedy: partial failures, and keeping state consistent.
Michael Kennedy: I'm sure many of you have written brutal code to
Michael Kennedy: keep the workflow moving and to track when you run into problems,
Michael Kennedy: but it's trickier than that.
Michael Kennedy: What if you have a long-running workflow and you need to redeploy the app or restart the server
Michael Kennedy: while it's running?
Michael Kennedy: This is where Temporal's open source framework is a game changer.
Michael Kennedy: You write workflows as normal Python code and Temporal ensures that they execute reliably,
Michael Kennedy: even across crashes,
Michael Kennedy: restarts,
Michael Kennedy: or long-running processes while handling retries,
Michael Kennedy: states,
Michael Kennedy: and orchestrations for you
Michael Kennedy: so you don't have to build
Michael Kennedy: and maintain that logic yourself.
Michael Kennedy: You may be familiar with writing asynchronous code
Michael Kennedy: using the async and await keywords in Python.
Michael Kennedy: Temporal's brilliant programming model
Michael Kennedy: leverages the exact same programming model
Michael Kennedy: that you are familiar with,
Michael Kennedy: but uses it for durability,
Michael Kennedy: not just concurrency.
Michael Kennedy: Imagine writing await workflow.sleep,
Michael Kennedy: time delta,
Michael Kennedy: 30 days.
Michael Kennedy: Yes, seriously,
Michael Kennedy: sleep for 30 days.
Michael Kennedy: Restart the server,
Michael Kennedy: deploy new versions of the app.
Michael Kennedy: That's it,
Michael Kennedy: Temporal takes care of the rest.
Michael Kennedy: temporal is used by teams at netflix snap and nvidia for critical production systems
Michael Kennedy: get started with the open source python sdk today learn more at talkpython.fm/temporal
Michael Kennedy: the link is in your podcast player's show notes thank you to temporal for supporting the show
Michael Kennedy: and you all keep talking about cordo because it's the foundation of what's happening with
Michael Kennedy: great tables right it's been a while since it was um been a while since i had jj and carlos on
Michael Kennedy: the podcast to talk about cordo but so maybe just give folks a bit of a refresher of what is cordo
Rich lannone: and then how that relates back to great tables um yeah so cordo is a like a like open source
Rich lannone: publishing system so you can make things like sites um like documents like books for
Rich lannone: instance uh you can make presentations uh it's probably a few more i'm missing and it's cross
Rich lannone: language as well and it and like you know code cells so it has computational notebooks is what
Rich lannone: they call them because they have cells which are basically computational cells which can accept
Rich lannone: which have different engines so you can like say like run some r code run some python some julia
Rich lannone: uh what have you many other things as well and then you can stitch them you know basically render
Rich lannone: them into into documents using handdoc for the most part and probably other things too for
Rich lannone: different output types and it just really batteries included has things like you just see in them on
Rich lannone: the site citations cross refs you know it's it's got it all essentially and so how it relates to
Rich lannone: to QuoraDoc and to GreatDocs.
Rich lannone: We're using QuoraDoc.
Rich lannone: But not really.
Rich lannone: I think with QuoraDoc,
Rich lannone: the way I see it is like,
Rich lannone: and correct me if I'm wrong, Michael,
Rich lannone: at QuoraDoc,
Rich lannone: you're creating a reference API,
Rich lannone: but you're still basically using QuoraDoc.
Rich lannone: You're within the QuoraDoc itself.
Rich lannone: You're still creating the Quora config.
Rich lannone: But with GreatDocs,
Rich lannone: it's kind of like QuoraDoc is a bit sort of like
Rich lannone: we're using it,
Rich lannone: obviously,
Rich lannone: but you don't have to know a lot about QuoraDoc.
Rich lannone: you can basically get by with just a few things you see,
Rich lannone: you know,
Rich lannone: in like the user guide and not have to like go deeply into Quarto.
Rich lannone: It sort of like hides it a little bit or doesn't really advertise it as much,
Michael Chow: even though we're using a lot.
Michael Chow: Just for some context.
Michael Chow: Yeah.
Michael Chow: I mentioned before I developed a tool called QuarterDoc,
Michael Chow: which is another documentation generator for Quarto.
Michael Chow: So just,
Michael Chow: just to clarify like the context.
Michael Chow: Yeah.
Michael Chow: Like QuarterDoc is a much more kind of like low level,
Michael Chow: no frills.
Michael Chow: So like the IBIS project uses it.
Michael Chow: So that's another pretty,
Michael Chow: pretty big Python tool,
Michael Chow: but it's like very like simple.
Michael Chow: It's more about like dump your API reference and then you're responsible
Michael Chow: for like customizing your website.
Michael Chow: And so it's for people who really want to like be in control and set it all up.
Michael Chow: I think Rich is kind of underselling.
Michael Chow: I think great docs is just dripping in style.
Michael Chow: I think that's the,
Michael Chow: one of the keys is it's made to be kind of like an all in one,
Michael Chow: something really nice out of the box that's opinionated.
Michael Chow: But I just want to clarify for context,
Michael Chow: QuartoDoc is another tool outside of Quarto.
Michael Chow: So I know we've checked a lot of tools out.
Michael Chow: But one thing that's interesting is I know,
Michael Chow: like when we look at great docs,
Michael Chow: it's easy to see like some of the stuff that jumps out.
Michael Chow: But there's actually,
Michael Chow: I think to Rich's credit,
Michael Chow: there's a ton of like little things inside great docs
Michael Chow: that you almost don't notice until you need them.
Michael Chow: Like there's a million little pieces to doc sites.
Michael Chow: And some of them are actually pretty intriguing.
Michael Chow: Like if you go to the great docs API reference,
Michael Chow: 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,
Michael Chow: including this little like filter bar.
Michael Chow: So if you click on the top left,
Michael Chow: there's a,
Michael Chow: you can sort of like filter on the page for different pieces.
Michael Chow: That's like,
Michael Chow: yeah.
Michael Chow: I think for just to illustrate the difference.
Michael Chow: So quarter doc is a really bare bones tool.
Michael Chow: It's like we generate an API for you.
Michael Chow: Great docs like this thing, this filter bar where you can like type in it and it shows you live on the page.
Michael Chow: Like it filters your reference items.
Michael Chow: That's just pure rich,
Michael Chow: just like wilding out on what docs could be.
Michael Chow: And I think there are like a million little examples of this kind of in great docs.
Rich lannone: Kind of. Yeah.
Rich lannone: Cause like I find little things that annoy me and I want to fix them.
Rich lannone: But,
Rich lannone: um,
Rich lannone: uh,
Rich lannone: and so this is my,
Rich lannone: this is almost like a,
Rich lannone: like a, like a Python site generator
Rich lannone: for,
Rich lannone: for me in lots of ways, but I'm hoping that other people feel these little pain points
Rich lannone: as well.
Michael Kennedy: I've certainly felt I've gone to,
Michael Kennedy: um,
Michael Kennedy: documentation sites and search for stuff on there.
Michael Kennedy: And then you see a little spinner searching,
Michael Kennedy: searching static site.
Michael Kennedy: What are we doing?
Michael Kennedy: Why am I waiting?
Michael Kennedy: This doesn't make any sense to me, but okay.
Michael Chow: Yeah.
Michael Kennedy: Yeah.
Michael Chow: Even the CLI button,
Michael Chow: like,
Michael Chow: oh, sorry, if you click that,
Michael Chow: that's like if you have a command line interface for your tool,
Michael Chow: which is so hot today,
Michael Chow: like AI loves command line interfaces.
Michael Chow: Cloud codes just bash executing everything.
Michael Chow: You know, a lot of people have CLIs.
Michael Chow: I think it also speaks a lot to Richestile that he created this spot for your CLI docs to live.
Michael Chow: Very important.
Michael Chow: And then at the top right,
Michael Chow: if you look,
Michael Chow: there's like a copy.
Michael Chow: You can copy the whole page to Markdown or view it as Markdown.
Michael Chow: I never would have thought of that.
Michael Chow: To me,
Michael Chow: I would never go that far to give people something nice.
Michael Chow: I don't know if I'm just like a curmudgeony engineer.
Michael Chow: I think Rich is just dreaming up,
Michael Chow: I don't know, different ways you could interact with docs,
Michael Chow: copy the page to Markdown.
Michael Chow: And I don't doubt that it's incredibly useful.
Michael Chow: To me, this strikes me as like...
Michael Chow: I think it's very useful, yeah.
Michael Chow: Yeah.
Michael Chow: When I saw that table graph for great tables,
Michael Chow: like breaking apart the table into every little piece,
Michael Chow: this strikes me as rich again,
Michael Chow: like imagining every little thing a doc site could do.
Michael Chow: So I think that's why I'm so kind of gassed up about great docs.
Michael Kennedy: This is delightful.
Michael Kennedy: And we're going to come back to AI stuff later, but we don't have that much time left,
Michael Kennedy: honestly,
Michael Kennedy: guys.
Michael Kennedy: We've been talking and not making a lot of progress because it's really, we're just diving into it.
Michael Kennedy: Docs talk.
Michael Kennedy: It's so fun.
Michael Kennedy: I know.
Michael Kennedy: It's so fun.
Michael Kennedy: But I can easily see I'm working on a project and I've got Claude or some codex or whatever,
Michael Kennedy: and it's just not getting it for a certain function.
Michael Kennedy: Just go over to the docs, hit copy pages,
Michael Kennedy: markdown, and just go, no AI,
Michael Kennedy: this is the docs, read it.
Michael Kennedy: Because giving it a markdown result of what this is versus all the nav and all the stuff,
Michael Kennedy: and it's trying to understand what's the essence of the page, if you tell it to just go to the page,
Michael Kennedy: really, really different.
Rich lannone: Yeah, it's been more immediate,
Rich lannone: I think.
Rich lannone: Also, you can change the URL if you really want to, to.md and just give it the URL.
Rich lannone: So many ways to do it.
Michael Kennedy: Yeah,
Michael Kennedy: yeah, yeah.
Michael Kennedy: I love that.
Michael Kennedy: So it said html.md.
Michael Kennedy: Yeah.
Michael Chow: That's really cool.
Michael Chow: So if you were plot code or reading the docs,
Michael Chow: you know, a lot of good stuff.
Michael Kennedy: Yeah,
Michael Kennedy: season tokens.
Michael Kennedy: Yeah,
Michael Kennedy: yeah, yeah.
Michael Kennedy: That's cool.
Michael Kennedy: Did I do that for Talk Python?
Michael Kennedy: I think I did.
Michael Kennedy: Yeah.
Michael Kennedy: You do that on Talk Python, by the way.
Michael Kennedy: You can just put.md on the end of any episode name,
Michael Kennedy: and it gives you the markdown equivalent
Michael Kennedy: that as well so which is all the rage yeah so i mean we're on the same vibes here i'm loving it
Michael Chow: you know what i mean and it might even help for context i'd be curious to hear your like when you
Michael Chow: added that markdown and some of your motivation for markdownifying your site i didn't do it for
Michael Kennedy: people i did it for ai and seo the machine stuff yeah for the machine so um i i added a i did an
Michael Kennedy: llms.txt to try to get the ais to understand the podcast better and some of the things that i gave
Michael Kennedy: was this ability to just put Markdown at the end,
Michael Kennedy: but also I added like a CLI and an MCP
Michael Kennedy: and different things for an API,
Michael Kennedy: search API.
Michael Kennedy: I'm like, okay, AI,
Michael Kennedy: there's 7.5 million words of content over 11 years.
Michael Kennedy: I want you to know about it and be able to use it.
Michael Kennedy: How many ways can I imagine giving something to it?
Michael Kennedy: And this render as Markdown was certainly one of them.
Michael Kennedy: I also added some silly stuff that's like for,
Michael Kennedy: just for me,
Michael Kennedy: because I've got, for example,
Michael Kennedy: I've got to update,
Michael Kennedy: say,
Michael Kennedy: the YouTube recommendations.
Michael Kennedy: So, or listings after the live stream,
Michael Kennedy: I want them to have like links and stuff.
Michael Kennedy: So I can say dot YouTube on the end
Michael Kennedy: and it gives me the contents for like the YouTube render.
Michael Kennedy: So it kind of was building on this,
Michael Kennedy: like how can I help myself be more efficient,
Michael Kennedy: but also machines?
Michael Kennedy: So anyway, that's the story.
Michael Kennedy: This is great.
Rich lannone: It's like Doc's workflow really,
Rich lannone: right?
Rich lannone: It fits in nicely.
Michael Kennedy: You know, circling back around,
Michael Kennedy: I'm really impressed with some of these little nuances
Michael Kennedy: that are super nice.
Michael Kennedy: I think that's great.
Michael Kennedy: Great talks.
Michael Kennedy: If you want to go further on this,
Rich lannone: it's basically just nicing up the docs
Rich lannone: and make them good for humans,
Rich lannone: but also consumable by LLMs or agents and such.
Michael Kennedy: Rich, it's a fad.
Michael Kennedy: We don't really need to worry about it.
Michael Kennedy: It's going to go away.
Michael Kennedy: It'll pass,
Michael Kennedy: yeah.
Michael Kennedy: The bubble's going to burst.
Michael Kennedy: We can just ignore it.
Michael Kennedy: It's going to be fine.
Michael Kennedy: No.
Michael Kennedy: So let's talk.
Michael Kennedy: I want to talk about a couple of things here.
Michael Kennedy: So let's just do like a real quick little walkthrough
Michael Kennedy: of maybe getting started with this.
Michael Kennedy: It's honestly not a whole lot to get started, but give us this.
Michael Kennedy: One of you all walk us through the quick start just so people know what's involved.
Rich lannone: Yeah.
Rich lannone: So really that command,
Rich lannone: like great docs init,
Rich lannone: that'll make the file that is basically what
Rich lannone: you need for the build.
Rich lannone: And with a lot of testing,
Rich lannone: it should work on many different Python package layouts and
Rich lannone: types.
Rich lannone: So you just need that.
Rich lannone: Of course, yeah, install great docs,
Rich lannone: install Porto as well.
Rich lannone: So we got that as well before that.
Rich lannone: But once you have those things, it should do what it says on the screen, basically show
Rich lannone: you stuff in the terminal,
Rich lannone: which is all positive.
Rich lannone: It's creating that great docs.yaml file.
Rich lannone: And it should be pretty minimal what's in there.
Rich lannone: It should actually also be a little bit dynamic.
Rich lannone: Based on your project,
Rich lannone: it'll craft the correct great docs.yaml file or the config file.
Rich lannone: And then you could go ahead and customize,
Rich lannone: but you might just jump to building your documentation
Rich lannone: because that's the next easiest thing.
Rich lannone: It's just another command, great docs build.
Rich lannone: and what you get is a great hyphen docs directory
Rich lannone: in your working directory.
Rich lannone: And that contains like the site folder.
Rich lannone: But you don't really have to worry about that
Rich lannone: because you have another command called great docs preview,
Rich lannone: which will basically launch like a web server
Rich lannone: and then put the site in your default browser,
Rich lannone: basically just like let you see the site locally.
Rich lannone: And then because I'm a big fan of like people know what's going on,
Rich lannone: so it should be totally a black box.
Rich lannone: I give on this page, like a structure,
Rich lannone: the basic structure of like how it should look
Rich lannone: in your working directory.
Rich lannone: But that's kind of it.
Rich lannone: And I believe the next step for most people
Rich lannone: will just be getting this on CI if they're satisfied
Rich lannone: and then just working from there,
Rich lannone: like modifying their initialization,
Rich lannone: not initialization,
Rich lannone: their config file
Rich lannone: to give the site more customization personality
Rich lannone: and there'll be authoring guides and things like that.
Michael Kennedy: You've got the really nice watch feature.
Michael Kennedy: So great docs build --watch.
Michael Kennedy: Yes.
Michael Kennedy: Which feels very Hugo to me.
Michael Kennedy: Like you're going to build it so you can look at it, but then you want to edit it.
Michael Kennedy: So just,
Michael Kennedy: if you see any changes,
Michael Kennedy: just rebuild,
Michael Kennedy: right?
Rich lannone: Yeah, exactly.
Rich lannone: Small sites will build fast, but this is way faster,
Rich lannone: obviously.
Rich lannone: So yeah,
Rich lannone: this is pretty essential for iterating,
Rich lannone: especially initially.
Michael Kennedy: Yeah.
Michael Kennedy: And what about this version?
Michael Kennedy: So this is an interesting aspect of the project.
Rich lannone: Versions.
Rich lannone: Well,
Rich lannone: essentially you may have,
Rich lannone: you know,
Rich lannone: multiple tagged versions of your site.
Rich lannone: And this, this is kind of like a wild thing.
Rich lannone: You can have different documentation sites based on your version because you have,
Rich lannone: for instance,
Rich lannone: new things in your API.
Michael Kennedy: Right. People maybe know that from Python where you can go up here and drop down.
Michael Kennedy: Exactly. Like version selectors.
Rich lannone: So this is kind of like just seeing like certain versions of your site and it gives you a selector.
Rich lannone: On the GreatDocs site itself,
Rich lannone: we have a selector which is maximal.
Rich lannone: It has like every single version from the very first.
Rich lannone: And you can cruise in there and you'll see that there'll be way less in the earliest versions.
Rich lannone: Like the,
Rich lannone: if you look at the user guide for 0.1,
Rich lannone: which gives a little icon,
Rich lannone: a little scary saying it's unsupported.
Rich lannone: If you look at the user guide, it's pretty sparse.
Rich lannone: Like it's, you know, it's not as long as the other one.
Rich lannone: And if you look at the reference as well,
Rich lannone: it'll have less items.
Rich lannone: So it's aware of like what's available in which versions.
Rich lannone: And so you sort of set that up yourself or you can just do it through that command.
Michael Kennedy: Is that based on get tags or what is that?
Michael Kennedy: Based on get tags.
Michael Kennedy: Yeah, that's right.
Michael Kennedy: Okay.
Michael Kennedy: I was wondering how does it even know?
Rich lannone: Yeah, you have to give it some information.
Rich lannone: Like you have to,
Rich lannone: of course, get the tags, but if you actually configure it to do what's doing here,
Rich lannone: like make the site,
Rich lannone: you just change your configuration to have,
Rich lannone: it's basically just like a small config that you have to do.
Rich lannone: And you can set labels and things like that.
Michael Kennedy: Can I wildcard it or have it somehow pick up all the versions?
Michael Kennedy: I mean, you don't want to pick up all tags, but it'd be like star dot star.
Rich lannone: I don't think we have version expressions like that yet.
Rich lannone: Yeah.
Michael Kennedy: Not yet.
Michael Kennedy: Okay.
Rich lannone: You know, throw it in there.
Michael Kennedy: I'm just thinking if I have a project with 27 versions over time.
Rich lannone: Yeah, you probably wouldn't do it through like this interface,
Rich lannone: like Great Docs build.
Rich lannone: This is just for like a pretty quick comparison.
Rich lannone: But if you would do it, like you probably put that in the config file and you'd have to
Rich lannone: manually edit those.
Rich lannone: But I think with a slot or something like that would be better.
Michael Kennedy: And there's an API,
Michael Kennedy: of course, if you want to just have a little control.
Michael Kennedy: Yeah,
Rich lannone: it's kind of, you wouldn't do this,
Rich lannone: but it's just,
Rich lannone: I threw it in there.
Michael Kennedy: Well,
Michael Kennedy: probably because your commands use that,
Michael Kennedy: right?
Michael Kennedy: Yeah, exactly.
Michael Kennedy: Might as well just let people know that.
Rich lannone: Just being transparent.
Michael Kennedy: I suppose. Yeah. Where do we want to go next? Let's,
Michael Kennedy: let's cover just a couple,
Michael Kennedy: couple of remaining things here while we're,
Michael Kennedy: we got time to have, what about open source
Michael Kennedy: sustainability?
Michael Kennedy: Like I know you all at Posit are doing a lot of things to open source
Michael Kennedy: your work and so on.
Rich lannone: Yeah.
Rich lannone: Well, we're pretty much like full-time doing open source work.
Rich lannone: So essentially,
Rich lannone: and so I think these projects have like long life cycles with the same maintainer
Rich lannone: for long periods of time,
Rich lannone: which is great for project stability and things like that. And like,
Rich lannone: you know,
Rich lannone: we're accountable for like, you know, issues that come in and for, you know, releases
Rich lannone: and making sure,
Rich lannone: you know, it's not,
Rich lannone: you know, like dead projects,
Rich lannone: you know, like all the way
Rich lannone: down or whatever.
Rich lannone: So I think,
Rich lannone: I think that's a great thing.
Rich lannone: And for instance,
Rich lannone: like great tables,
Rich lannone: I've been at this since the beginning,
Rich lannone: GT,
Rich lannone: which is where it came from since 2017.
Rich lannone: So I think that
Rich lannone: helps a lot. Adds a lot of credibility to these projects that are not just being abandoned.
Rich lannone: There's
Rich lannone: no fear of it being abandoned or things like that.
Rich lannone: There's,
Rich lannone: there's a person there at least.
Michael Kennedy: Yeah, and I think Posit's found an interesting business model
Michael Kennedy: that's been long-term sustaining,
Michael Kennedy: but still allows you, as you said,
Michael Kennedy: to sort of work in open source.
Michael Kennedy: Michael, we're joking.
Michael Chow: Yeah,
Michael Chow: it's really interesting.
Michael Chow: And it's almost like not diving crazy deep
Michael Chow: and doing a podcast.
Michael Chow: My favorite thing to say to people is that
Michael Chow: we have a really large open source engineering team,
Michael Chow: dozens of open source engineers.
Michael Chow: People often ask, how does Posit pay the bills
Michael Chow: for people to work on open source?
Michael Chow: And my favorite thing to say is like,
Michael Chow: we have a bunch of boring enterprise tools and I'm
Michael Chow: no shade on pause.
Michael Chow: I actually think that this is the best case scenario.
Michael Chow: Like we have a lot of tools that solve really painful problems.
Michael Chow: If you're an enterprise,
Michael Chow: they could be useful in other settings,
Michael Chow: but it's like,
Michael Chow: how do I
Michael Chow: run a report every day?
Michael Chow: Or how do I host like Jupyter notebooks or VS Code for my say like data team or our studio?
Michael Chow: Those essentially pay the bills.
Michael Chow: That's Posit Connect and Posit Teams.
Michael Kennedy: You've got a team of data scientists,
Michael Kennedy: but you don't necessarily have a DevOps team,
Michael Kennedy: but you still want to have their stuff running reliably,
Michael Kennedy: right?
Michael Chow: Yeah,
Michael Chow: and it's a hard problem.
Michael Chow: If you're a company,
Michael Chow: right, these are kind of tricky problems.
Michael Chow: Or you have like a really mean IT team.
Michael Chow: A cruel IT team could hamstring you for years.
Michael Chow: But that's just to say we get to work on open source
Michael Chow: because these tools exist.
Michael Chow: And I think Posit exists,
Michael Chow: I think, because the maintainers care so much about open source.
Michael Chow: I will say in terms of sustainability,
Michael Chow: one interaction I've really liked over the years is like in the docs realm,
Michael Chow: there's this person.
Michael Chow: I only know him as Pawe Moy,
Michael Chow: his GitHub handle.
Michael Chow: I think it's Maté or Timothy in France,
Michael Chow: I think.
Michael Chow: But he maintains the tools upstream of tools like Portadoc and GreatDocs.
Michael Chow: And we've interacted a bit in the past where I've done PRs on his tools.
Michael Chow: One's called Griff.
Michael Chow: And I think that's such an important part of sustainability too,
Michael Chow: is that he works on a documentation tool,
Michael Chow: MakeDocStrings.
Michael Chow: But we're all able to collaborate on his tool, Griff,
Michael Chow: that actually powers all of our documentation sites.
Michael Chow: So I think that's a really important piece.
Michael Chow: I think to your point about being at PyCon and seeing people,
Michael Chow: I think us as open source
Michael Chow: maintainers chatting and even contributing and working on say like upstream tools is
Michael Chow: a really important part of keeping the ecosystem healthy and sustainable.
Michael Chow: We're not like multiple doc tools competing to a degree.
Michael Chow: I do think they compete,
Michael Chow: but ultimately like we're working on open source because we're
Michael Chow: passionate.
Michael Chow: And I think it helps to collaborate on our kind of like shared tools.
Michael Kennedy: A hundred percent agree.
Michael Kennedy: Very cool.
Michael Kennedy: Now,
Michael Kennedy: Rich, you mentioned that pretty new project.
Michael Kennedy: Yeah.
Michael Kennedy: Where are we going?
Michael Kennedy: What's on the roadmap?
Rich lannone: Yeah, lots of things.
Rich lannone: I even have a roadmap on the site if anyone's interested.
Rich lannone: But I think it'll be like a lot more like documentation for different things, like new things.
Rich lannone: Like the other day,
Rich lannone: I was suggested to create documentation for MCP servers.
Rich lannone: I was like,
Rich lannone: good idea.
Rich lannone: We don't really have that.
Rich lannone: And it's pretty easy to document JSON,
Rich lannone: essentially.
Rich lannone: So we can take that apart,
Rich lannone: parse that, and present something.
Michael Kennedy: that's a good point because if you look at the mcp servers they don't have structure in the way that
Michael Kennedy: traditional projects do right they don't just have like a separate function for each thing they've got
Michael Kennedy: this kind of weird invocation entry point where you pass like the tool you want to use and yeah it's
Rich lannone: documentation suggestions things like that uh so i think we could do a pretty good job there that's
Rich lannone: the idea is pretty new but like i guess we're yeah just trying to be where or go where things are
Michael Kennedy: going and be a little bit ahead so would that somehow show itself as like where you've got the
Michael Kennedy: um the api and the cli would there also be an mcp or what do you think it's gonna be a bit crowded
Michael Kennedy: so i'm rethinking i know yeah yeah i was like i don't really know this would be it like but no
Rich lannone: that's not quite it there's you know maybe one or two more things uh so it might be just a drop down
Rich lannone: nav on the top like a drop down on the top nav so that's part of the part of like uh what i
Rich lannone: have to think about.
Rich lannone: But there's things like that. And also like a recent thing we just did,
Rich lannone: and this is very new, so it's almost like it's new enough,
Rich lannone: is like skills,
Rich lannone: like publishing skills
Rich lannone: and making them available and making them browsable,
Rich lannone: right?
Rich lannone: So on the very,
Rich lannone: it's not top
Rich lannone: level.
Rich lannone: If you go to the first page,
Rich lannone: there's like a sidebar on the right,
Rich lannone: which gives you a lot of
Rich lannone: metadata.
Rich lannone: And one of the first few things is skills.
Rich lannone: And that gives you like a page on how to install
Rich lannone: these skills. So it's kind of like a,
Rich lannone: almost like a way not to just distribute,
Rich lannone: but a way to sort of
Rich lannone: like get ahold of skills.
Rich lannone: And there's a nice little sort of like disclosure there,
Rich lannone: install these skills,
Rich lannone: it gives you instructions on how to do such things.
Rich lannone: And you can just browse the skills below
Rich lannone: and see what's there.
Rich lannone: You might just take bits of them,
Rich lannone: make your own skill,
Rich lannone: or you might just say,
Rich lannone: no, these all look good.
Rich lannone: I'll just follow these instructions
Rich lannone: and install them for my project or globally.
Michael Kennedy: So we're trying to make that a bit easier.
Michael Kennedy: Yeah, it's super cool.
Michael Kennedy: Yeah,
Michael Kennedy: that kind of brings me to the last thing
Michael Kennedy: that I wanna talk about is the AI-ification.
Michael Kennedy: And by that, I don't mean,
Michael Kennedy: How do I, are you using AI to write it or not?
Michael Kennedy: Like I imagine there's some degree of that or whatever,
Michael Kennedy: but if I am a person with a project package
Michael Kennedy: or something I want to document,
Michael Kennedy: AI is really good at going like,
Michael Kennedy: well,
Michael Kennedy: let me pull out all these pieces
Michael Kennedy: and then like,
Michael Kennedy: you know, sketch some stuff out for you.
Michael Kennedy: Is there,
Michael Kennedy: you know, and I can see now
Michael Kennedy: that you pointed me in the right direction
Michael Kennedy: that there's a whole AI section,
Michael Kennedy: like how do AIs work with great docs,
Michael Kennedy: right?
Michael Kennedy: And so you've got the llms.txt,
Michael Kennedy: which is really nice.
Michael Kennedy: you know, I referenced that before.
Michael Kennedy: People don't know there's an,
Michael Kennedy: this comes from, I believe from Jeremy Howard.
Michael Kennedy: Yeah,
Michael Kennedy: that's right.
Rich lannone: Yeah, we looked at this closely, yeah.
Michael Kennedy: Putting,
Michael Kennedy: yeah, so did I,
Michael Kennedy: and I find it super interesting.
Michael Kennedy: Like this,
Michael Kennedy: the idea is that if you,
Michael Kennedy: you know, there's a robots.txt
Michael Kennedy: and a sitemap.xml.
Michael Kennedy: These are standard web things on sites
Michael Kennedy: that humans rarely use to get any value from,
Michael Kennedy: but machines and traditionally search engines
Michael Kennedy: really,
Michael Kennedy: really do.
Michael Kennedy: And so, well, what do we put for AI
Michael Kennedy: to make it better, LLMs and so on?
Michael Kennedy: is this llms.txt file that describes in Markdown
Michael Kennedy: to the LLMs, like how you can better work with this.
Michael Kennedy: With that,
Michael Kennedy: you all have that, right?
Michael Kennedy: So you've got your llms.txt and the full one.
Michael Kennedy: You know, this is not something I'm doing.
Michael Kennedy: Maybe I need to do a full one.
Rich lannone: This one's interesting.
Rich lannone: It's a lot.
Rich lannone: So basically it's the entire bit of documentation
Rich lannone: distilled down, not distilled,
Rich lannone: but like written as one file,
Rich lannone: essentially.
Rich lannone: All doc strings mashed together,
Rich lannone: you might say,
Rich lannone: including guide material as well.
Rich lannone: So that's all in there.
Michael Kennedy: Yeah, and you've got these skills as well,
Michael Kennedy: which is looking super interesting and also a pretty neat,
Michael Kennedy: the CLI that you've created a couple of things on that.
Michael Kennedy: First of all, that it will actually install the skills.
Rich lannone: Yeah.
Rich lannone: So if you're an author,
Rich lannone: you would just use great docs,
Rich lannone: install,
Rich lannone: skill install,
Rich lannone: and then they may be the name of your library for other people.
Rich lannone: That's what other people would see on their sites.
Michael Chow: That's an interesting piece.
Michael Chow: Cause if I'm an,
Michael Chow: I have to admit, I haven't seen the skills piece a lot,
Michael Chow: but if I'm understanding rich too,
Michael Chow: this means great docs is also for like kind of all users,
Michael Chow: right?
Michael Chow: Like people who are interested in reading or consuming docs or using it with AI.
Michael Chow: Is that right?
Michael Chow: I see.
Michael Chow: So that's kind of where we're going more and more.
Michael Kennedy: Yeah.
Michael Kennedy: So it looks like you're really leaning into making great docs,
Michael Kennedy: something that works well
Michael Kennedy: if you're trying to generate docs and maintain with AI,
Michael Kennedy: right?
Rich lannone: We also want, if you point your agent at this site,
Rich lannone: it should be able to find these things
Rich lannone: pretty quickly.
Rich lannone: And you can actually like use tools.
Rich lannone: Like there's one called whatdoagentsc.runtime.app.
Rich lannone: Just search it up.
Rich lannone: You can put it in your URL and it'll show you what pieces are picked up by different agents.
Rich lannone: It actually simulates it really nicely.
Rich lannone: And I found that this sort of validated things that different agents do pick up LLMs.txt, LLMs.full.
Rich lannone: And there's other little pieces of metadata,
Rich lannone: things that go in the meta tag that can be picked up to like robots.txt and very accept,
Rich lannone: things like that.
Rich lannone: So we're working towards making this even easier.
Rich lannone: 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.
Michael Kennedy: Very exciting.
Michael Kennedy: I love it.
Michael Kennedy: Okay.
Michael Kennedy: And also just you mentioned that there's the CLI,
Michael Kennedy: right?
Michael Kennedy: Or I don't know what I was mentioning.
Michael Kennedy: But the fact that there is a CLI is another really great enablement.
Michael Kennedy: 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.
Michael Kennedy: Here's the docs and the skill.
Michael Kennedy: Make this happen.
Michael Kennedy: You know, right?
Michael Kennedy: Yeah.
Rich lannone: Yeah.
Rich lannone: And you can even,
Rich lannone: the skills I include,
Rich lannone: like in great docs could be used to author your
Rich lannone: own great doc site.
Rich lannone: Like there's all sorts of things in there for like just how it works and like, you know,
Rich lannone: like,
Rich lannone: like writing pages,
Rich lannone: they're kind of split up into like multiple name skills.
Michael Kennedy: So you can, you can just use that or make your own skills.
Michael Kennedy: Yeah.
Michael Kennedy: Very neat.
Michael Kennedy: All right.
Michael Kennedy: Two really quick things.
Michael Kennedy: I know we're pretty much out of time for you guys.
Michael Kennedy: One,
Michael Kennedy: what I get out of this is just a static site and I can just host it on any static
Michael Kennedy: site place.
Michael Kennedy: Okay.
Michael Kennedy: That's really good.
Michael Kennedy: For sure.
Michael Kennedy: it could be netlify it could be you know pages for me on provide some fine grained instructions
Rich lannone: for different uh hosts and things like that github pages like seems like a nice default
Rich lannone: it's not you know but of course yeah netlify versal things like that we provide some hints
Michael Kennedy: that it works for me i i was running on netlify for a while but i actually had my monitoring
Michael Kennedy: software monitoring it and it actually went down surprisingly often i'm like why is my static site
Michael Kennedy: going down this makes no sense so i've ended up recently i've already got like a big server with
Michael Kennedy: tons of sites so i just i'll just have a config on nginx that just runs it you know and so there's
Michael Chow: a lot of options there yeah it's so interesting not not to dwell on it but i do remember you saying
Michael Chow: i think on a podcast with um hugo talking about your hugo van anderson your approach that you're
Michael Chow: you have way less downtime than even some of the cloud providers so not not to go too deep
Michael Kennedy: that's interesting to hear about let's it is i i could go for hours on this so be careful there
Michael Kennedy: michael i find it really interesting that you just the extreme simplicity of like i've got a server
Michael Kennedy: and either it's got a self-contained python and database runtime or it's just even a static site
Michael Kennedy: that goes a long ways you know really long ways instead of like all the 100 connected services
Michael Kennedy: powered by some dynamic thing underneath.
Michael Kennedy: And if one of them goes down, it takes a chunk with it.
Michael Chow: Yeah,
Michael Chow: yeah,
Michael Chow: for sure.
Michael Kennedy: Maybe that was my last question.
Michael Kennedy: I think just the deployment side of things is really interesting.
Michael Kennedy: So it sounds like just wherever,
Michael Kennedy: right?
Michael Kennedy: Anything that serves static files, you get to go.
Rich lannone: Pretty much, yeah.
Rich lannone: Because you get the site directory and you just go with that.
Rich lannone: Like it's complete site in a directory.
Michael Kennedy: Yeah, okay.
Michael Kennedy: So the second, now I remember, the second thing I wanted to talk about was
Michael Kennedy: if I go over to the user guide and I do a quick start,
Michael Kennedy: You show me the structure and I get this here,
Michael Kennedy: this yourprojectgreatdocs.aml, greatdocs, et cetera, et cetera.
Michael Kennedy: So it looks like the recommendation is to have great docs
Michael Kennedy: as a sub directory of your actual things that it is documenting.
Michael Kennedy: Is that right?
Michael Kennedy: Sort of, but you don't have to keep it.
Rich lannone: I mean, like it's just going to appear there when you render locally
Rich lannone: and you can look at the site, you can preview it,
Rich lannone: but you can just delete it.
Rich lannone: I can have it on CI or whatever,
Rich lannone: like on your CI system or however you're deploying.
Michael Kennedy: Like your step could be build and then copy and then delete.
Michael Kennedy: Yeah,
Michael Kennedy: exactly.
Michael Kennedy: The folder,
Michael Kennedy: not necessarily the YAML.
Michael Kennedy: Well, yeah, you want to keep that.
Rich lannone: Yeah,
Rich lannone: yeah,
Rich lannone: that's config.
Rich lannone: So that, commit that.
Rich lannone: And hopefully I sort of like outlined it here on this page,
Rich lannone: what should be like,
Rich lannone: you know,
Rich lannone: committed.
Rich lannone: And we automatically .gitignore some things too.
Rich lannone: So you don't accidentally commit things.
Rich lannone: You don't have to.
Michael Kennedy: If I want to do the freeze though, I probably have to keep it.
Michael Kennedy: Yeah.
Rich lannone: No,
Rich lannone: we actually work around that.
Rich lannone: So we do like a, like a pre.
Rich lannone: We got a little system there.
Rich lannone: So I know it wipes everything out,
Rich lannone: but we have a freeze mechanism
Rich lannone: that sort of works around
Rich lannone: this sort of like ephemeral nature of things.
Rich lannone: Yeah,
Rich lannone: still uses coral freeze.
Rich lannone: So it just does it a little bit different.
Michael Kennedy: Yeah, very interesting.
Michael Kennedy: Okay, final thoughts.
Michael Kennedy: People are interested in this.
Michael Kennedy: They want to get started.
Michael Kennedy: What do you tell them?
Rich lannone: Yeah, just check out the site.
Rich lannone: I'm hoping you'll be not wowed,
Rich lannone: but that it will resonate a little bit
Rich lannone: and the site should demonstrate what's possible.
Rich lannone: And again,
Rich lannone: like, you know,
Rich lannone: Even just like have your agent,
Rich lannone: like, you know, like have some AI,
Rich lannone: take a small Python package
Rich lannone: of yours and see what it could do.
Rich lannone: Take it for a little spin.
Rich lannone: And if there's anything that you think is missing or lacking,
Rich lannone: just drop me a line,
Rich lannone: like
Rich lannone: through the issues.
Rich lannone: That's like,
Rich lannone: that's basically it.
Michael Kennedy: Can I publish on read, read the docs?
Rich lannone: I don't think we have that yet.
Rich lannone: Yeah.
Rich lannone: I actually never even considered that as a, as a publishing point.
Michael Kennedy: One of the standard places to put docs,
Michael Kennedy: not necessarily required,
Michael Kennedy: but it's, it'd be interesting,
Michael Kennedy: you know?
Rich lannone: Okay.
Rich lannone: I'm going to log that down.
Rich lannone: That's already like,
Rich lannone: that's a good one.
Michael Kennedy: All right. We're rewriting the roadmap live here.
Michael Chow: Yeah.
Michael Chow: That's a toughie.
Michael Chow: You threw down the gauntlet,
Michael Chow: you know, this is it.
Michael Kennedy: Sounds good.
Michael Kennedy: Well,
Michael Kennedy: I really appreciate you both being here.
Michael Kennedy: Michael,
Michael Kennedy: you want to have a final word as well of inspiration for folks?
Michael Kennedy: What a great question.
Michael Chow: I,
Michael Chow: my, my final nudge might be like,
Michael Chow: we talked a lot about generating docs, the kind of technical activity.
Michael Chow: I do think there's this world of how do you write docs?
Michael Chow: Like what should your content be?
Michael Chow: And what should your sections of your doc site be?
Michael Chow: Obviously we're saying goodbye.
Michael Chow: So that's,
Michael Chow: we don't want to open that can of worms.
Michael Chow: But I just wanted to cast a light on that.
Michael Chow: That is a freaky big area on its own.
Michael Chow: I don't have great answers.
Michael Chow: So I'm just throwing some problems on people's laps.
Michael Chow: But I think that's a neat freaky area that is worth checking out.
Michael Kennedy: I think what you're doing is you're setting the stage for another episode in the future.
Michael Kennedy: Yeah, that's right.
Michael Chow: We're just trying to make it a three,
Michael Chow: you know,
Michael Chow: like a trilogy.
Michael Chow: So we're trying to get our third visit in.
Michael Kennedy: Perfect.
Michael Kennedy: All right.
Michael Kennedy: Well,
Michael Kennedy: Rich,
Michael Kennedy: Michael,
Michael Kennedy: thanks for being here.
Michael Kennedy: It's great as always.
Michael Kennedy: Thanks so much for having us.
Michael Kennedy: Yeah.
Michael Kennedy: Bye.
Michael Kennedy: Thanks.
Michael Kennedy: This has been another episode of Talk Python To Me.
Michael Kennedy: Thank you to our sponsors.
Michael Kennedy: Be sure to check out what they're offering.
Michael Kennedy: It really helps support the show.
Michael Kennedy: This episode is brought to you by Sentry.
Michael Kennedy: You know Sentry for the error monitoring,
Michael Kennedy: but they now have logs too.
Michael Kennedy: And with Sentry,
Michael Kennedy: your logs become way more usable,
Michael Kennedy: interleaving into your error reports to enhance debugging and understanding.
Michael Kennedy: Get started today at talkpython.fm/sentry.
Michael Kennedy: And it's brought to you by Temporal,
Michael Kennedy: durable workflows for Python.
Michael Kennedy: Write your workflows as normal Python code,
Michael Kennedy: and Temporal ensures they run reliably,
Michael Kennedy: even across crashes and restarts.
Michael Kennedy: Get started at talkpython.fm/Temporal.
Michael Kennedy: If you or your team needs to learn Python,
Michael Kennedy: we have over 270 hours of beginner and advanced courses on topics ranging from complete beginners to async code, Flask, Django,
Michael Kennedy: HTML,
Michael Kennedy: and even LLMs.
Michael Kennedy: Best of all,
Michael Kennedy: there's no subscription in sight.
Michael Kennedy: Browse the catalog at talkpython.fm.
Michael Kennedy: And if you're not already subscribed to the show on your favorite podcast player,
Michael Kennedy: what are you waiting for?
Michael Kennedy: Just search for Python in your podcast player.
Michael Kennedy: We should be right at the top.
Michael Kennedy: If you enjoy that geeky rap song,
Michael Kennedy: you can download the full track.
Michael Kennedy: The link is actually in your podcast below or share notes.
Michael Kennedy: This is your host,
Michael Kennedy: Michael Kennedy.
Michael Kennedy: Thank you so much for listening.
Michael Kennedy: I really appreciate it.
Michael Kennedy: I'll see you next time.
Michael Kennedy: of getting old.
Rich lannone: We tapped into that modern vibe
Rich lannone: overcame each storm.
Michael Chow: Talk Python To Me.
Michael Chow: I sync is the norm.
Michael Chow: Продолжение следует...