Great Docs - Talk Python Live Stream

Rich, Michael, welcome back to Talk Python to Me. Awesome to have you both back on the show. Yeah, thanks for having us. Yeah, for sure. We're going to talk about great things. I know, it's going to be a great show. It's undoubtable, right? I have no doubt. It's a great day, you know, and we're ready for, I think what's going to be a great chat. About great docs, great tables, all of those things. All the great things.

Yeah, so I had you on to talk about great tables, which was really fun. You're both from Posit. And other than that, maybe let's do a quick introduction for folks. I mean, I don't know why anybody would not have listened to the great tables episode. No, we honestly, we get a bunch of new listeners all the time. So yeah, let's do a quick round of introductions. Who are you? What do you do? Why are you working on this project? Rich, start with you.

Yeah. Yeah, I'm Rich. I work at Posit, PBC. I've been doing traditionally lots of R stuff, like in the past, but more lately, this is like the last three or four years, a lot more Python stuff. And actually, Michael, who's with me today, he taught me a lot about Python. Like, I was pretty bad starting. I mean, I used in the past, but I was open source stuff. I was bad. Michael has so much patience, though. So he helped me get up to speed over a period of a year or so. So I owe a lot to him. And he's a great guy.

That's really cool. I agree with that. I think it's hard to change a language. It's hard to switch to another language. And maybe you could speak to that real quick before Michael jumps in. And just, I've done that a couple times. You know, you spend so much time and energy and effort and getting really good at not just the language, the tools, the ecosystem, everything. And then you're like, oh no, I think I have to go over there for a while. Yeah, it feels like a bizarre situation. Like, I know what I could be doing, what I should be doing, like, theoretically, but things just don't jive sometimes. It's like, oh, yeah, but then you get used to it. And then your previous language degrades. It's kind of like that sort of thing.

It's a little bit sad in that regard. But for me, the real challenge was, I have such a deep knowledge and mastery of this technology. And if I switch, at least the first time or two I did, I felt like, I'm going to go back to the noobiest of noobs. And it's going to feel really bad. And I worked so hard for this knowledge and this experience. Why am I going to do this? Maybe I should never do that. It was a big deal for me. I want to say that for other people out there who are not necessarily going R to Python, but just one tech to another. Yeah, it's humbling, like I said. And well, you know, with a good mentor and lots of patience, it can happen. Yeah, it's good to expand your skills, but the initial decision is rough.

But for me, the real challenge was, I have such a deep knowledge and mastery of this technology. And if I switch, at least the first time or two I did, I felt like, I'm going to go back to the noobiest of noobs. And it's going to feel really bad. And I worked so hard for this knowledge and this experience. Why am I going to do this? Maybe I should never do that. It was a big deal for me.

Michael, you've been shepherding rich along the way. I love it. Tell us about yourself. Yeah, I wouldn't even say shepherding, or maybe there's like, some mutual shepherding going on. So I'm Michael Chow. I'm a software engineer at Posit and have been for about four years on the open source team. Yeah, and I, so I've worked with Rich on things like great tables. And I think that, yeah, I'm really interested in Python. I work on Python full time.

It, I think if I had to send back what what Rich is really good at, Rich just has this crazy freaky sense of style. And I think that's one thing that's drawn me to work with him on things is you just never know, like, to be totally honest, people at Posit just never know what Rich is going to pull out. And I don't think any of us could have imagined it. He's loose. He's our wildcard. And it's been interesting, because you can imagine like a programming language. Yeah, you could be like, oh, this person taught me this programming language. I don't really know how you teach Rich's style. But I'm, I feel like I'm kind of along for the ride. I'm like eating popcorn, helping out. And I think tools like great docs really reflect that this interesting sense of style or great tables. He's just dipped into this rich history of table styling. How would you style it to present and maybe publish it? 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.

Introducing Tablin the mascot

Yeah, that's really cool. You know, certain people just have a knack for APIs and the way that develop, you know, the developer UX sort of thing. That's cool. I am personally I'm excited for the mascot. Rich, I am. I blew your cover. We were. Yeah, so Michael and I were talking a little bit at PyCon about Tablin. Tablin, yes. He hasn't been tried out very much. Mascot wizard. Who is Tablin, though, I wonder. He's just a little table guy, little table dude, and appears, gives you help, and then disappears just as fast.

He isn't fully realized. He's always thinking of you. He's never thinking of himself. You know, he's showing up, helping you out. He's like the new Zippy or Bob, but much cooler because he's a table. Yes, absolutely.

And I do think this speaks to our dynamic where Tablin just appeared one day, like while we were preparing a PyCon talk two years ago, Tablin just appeared in the slides. And I didn't know who Tablin was. And I was like, who or what is this? It was like a slide of a table and Tablin was popped out on the side was saying, good job. And I was like, who's this spreadsheet with eyes and a mouth cheering people on? And Rich was like, it's Tablin, of course. Yeah, it's helpful to have a little dude that just wants to help. It's like having a pet, like a cat.

PyCon reflections

So, Michael, we had the great opportunity to meet up at PyCon just last week. I don't know how you feel about it personally. I'm still just a little bit recovering from the whole energy that was extracted from me. But it was really fun. And maybe give us your thoughts on PyCon and how'd that go? Yeah, it's a great question. It's so interesting because we work on tools for data analysis, but PyCon is much more general. It's almost like all things Python. I think it's a really interesting conference versus like a PyData or a SciPy, which are way oriented towards like data tools specifically.

But I love it. I find it really nice to be able to drop in and talk to just the full range of Python people who maybe have never used or done a lot of data analysis. So, I find it really interesting to talk to folks who maybe almost universally, I think everybody has touched Pandas, the library for data frames. And so, that's the like funny kind of like point you can always talk to anyone about at PyCon. But I find it really nice and I find the like PyCon organizers and the sort of Python Software Foundation. It's just so down to earth that, yeah, I really love dropping in. It doesn't feel super corporate. It feels like they're really like a group of passionate volunteers putting this like pretty big conference on. So, yeah, I always love dropping in, even if it's like a kind of broader audience than the like data crew.

I'm curious your experience. Have you gone to a lot of PyCons? I think my first one, when was my first? Mid-teens, I would say 2015, 2016, something like that. I'd probably have gone to maybe two thirds since then. Most. I mean, we did have COVID in the middle. That was challenging. But yeah, I've been to a fair number and I really enjoy it. For me, it's just nice to get together, meet folks like you and everyone else and just kind of remember, hey, this is a community of humans and not just docs. Never mind, I mean, docs are great. We're going to talk about how great docs can be. It's also nice to just have these human connections and just connect with people outside of width, but also outside of technology, right? Like, hey, let's just go sit in the sun for a while and talk. Have you seen the sun lately? No, I haven't seen it either. Let's go sit there.

Great Tables recap

Let's start our journey here. Let's just do a quick review of Great Tables. Because I know Great Tables was one of the inspirations for Great Docs. So we all three of us got together last year, I guess, to talk about Great Tables. So who wants to just do a quick reminder of this one? I'll go. So basically, yeah, Great Tables. It's a, maybe not being people notice, it's a port of an R package called GT. Not that important, but like the idea is as good as it was then. You want display tables, what I call them, essentially summary tables, like static tables. And you want to present them, say, in a notebook or say, like in some other publishable document as HTML. We also have a LaTeX output format. But the idea is you compose tables step by step. You know, you add a header, you want a title, you get that too. You structure the table. You can format different cells, like usually entire columns of cells. And you can also style a table, which could be like, you know, like changing orders, adding cell backgrounds, things like that.

And really the idea is like to make a table that you might see like in a print publication. But using your data, like directly, like using a data frame. So you have the data in a form which is amenable to a summary table. And then in just a few like method calls, you've got the table.

What strikes me about this, you know, when we had our conversation last year, is just how much more there is to think about with tables than, you know, just an Excel-like thing. I came away realizing that it goes way deeper and there's a lot more nuance. 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. Is his name Tufty? No, no, no, Tufty. Tufty, yes. He's just like, oh, I see, like there's some lines and stuff. Like, no, no, no, no, hold on. There's a lot going on. Like there's many things you can communicate subtly without just being like, well, let's just call this out. Like, no, you don't even have to call it out. It's communicated through something more interesting.

You know, and Tufty is that about just presenting sort of scientific information in general, but I felt that way about tables as well. Yeah, it's pretty well. We talked about this in our talk a few years back in PyCon. How, like, you can tell a story with a table or you can communicate data in a better way, you know. not a more optimized way, but a more legible way, where like, your main point is like, describe like a title and a subtitle. And you have notes at the bottom. And you can guide people through an analysis summary that way. And so just like with many different things, there's a good way to do it. And we're a better way to do it.

Yeah, there's, you could just look at certain types of presented information. You know, well, that looks really professional, or that looks really, really good. But I don't know why. You know what I mean? That was good, but I can't put my finger on exactly what is really different, but that's really good and that's not, you know, and I feel like Great Tables kind of leans into that. Yeah, I guess it takes the tufting principle to like having just the right amount of ink, I guess, like not too much, just enough to communicate the structure of things, like the sort of like the architecture of the data you're laying out, and not doing much more than that. So there's, there's a lot of that that goes into this, as a default thing.

To the Tufti point too, Tufti's website, Tufti has like all of these just dumps of examples, just like example plot, example plot, example plot, it's almost like a very rough notebook. And I feel like with Great Tables, it was kind of similar, like, when I first came on, I knew basically nothing about this topic. And I saw the components of the table diagram, so you have it pulled up, but it has like a table broken apart into all its pieces, like a title, subtitle, there's this funny thing called the stub head, and spanners. And I thought, like, does a person really need to know all this? But I think to the point of Tufti, like, maybe what you're getting at too is Tufti really dives into like, very specific, almost like dimensions of how you could represent data. One thing he gets really into is like spark lines, this idea that, like, how far could you get with a line that basically doesn't have any access labels, but it's just like a trend? Like, is it going up? Or is it going down? And that happens a lot in tables, you'll put like, these spark lines in a cell. If you're looking at stocks, you'll have like the stock numbers, and then you have a spark line that like indicates the kind of trend. So people can grab it really fast.

But I find what's interesting about Tufti is just that willingness to dive in so detailed about this one, very specific action. And I feel like this table diagram is sort of similar to me that the willingness to like break it apart so thoroughly. At first, I wasn't really convinced. It seemed like a lot of work. But yeah, I think to your point about Tufti, once you start looking at examples, you start to realize this kind of captures the like, flavor, or design of like good examples out there in the world. Yeah, yeah, I think it's really out there. Like initially, my idea too is like, oh, this is too much. But naming things is so important. Otherwise, you're just awkwardly describing something over and over again. Like that cell to the top left, or these cells off to the side. And eventually, you just have to give it a name, even if it's not the best name. And these are actually names I stole from like... basically a census manual on tables, I think, written in 1949. Great ideas, like, wonderful book, and it's on the web as a PDF, still.

Surveying the docs landscape

So the next thing I want to talk about is just sort of surveying the landscape of what is out there, because we're going to talk about great docs, and great docs can generate static sites. Some, there's some existing tools that generate docs as static site, there's some really good tools that just generate static sites that maybe people could put into docs, like, there's a lot of things that are somewhat similar. There's also stuff that's in the same space, but different. So maybe we could kind of go through and, you know, like, I know you, you all have mentioned Sphinx is a real popular one in the Python space. There's MK docs, I had Martin from Zenzicle on not too long ago. So maybe we could talk first about some of the existing tools that are, I guess, as similar as possible to what you're doing.

Yeah. Michael, would you like to speak on this? Because I know you did a deep dive recently on these. Yeah. So Sphinx, I think, and maybe to kick off some helpful context to great docs is that, yeah, we, I worked a lot on early support for documentation with a tool called QuarterDoc. But Rich actually took it to the next level. And this goes to, I think, Rich's style with great docs. So a lot of bizarre, like, experience looking at the history of Python docs. I think Sphinx is one of the OG site builders.

I can't, I think this is the case. So I think one interesting fact is, as I understand it, I think Python.org, don't quote me on this, I think it was originally done in, like, LaTeX or something like that, the Python docs. And I think that they moved to Sphinx at some point. So, like, Sphinx has a really interesting history in Python. Like, if you go back 25, 30 years, Python docs had to exist using some tool, right? And at some point Sphinx emerged as kind of like this dominant site builder for Python and Python docs. Yeah, does it say? Yeah. So Python docs are in Sphinx. You know, this Python doc site has a how-to, Python how-tos. This is another weird fact. The how-tos emerged, I don't remember exactly when they emerged. It was like in the last 30 years, I think, as part of the Linux project. So the term how-to, as I understand it, emerged in the Linux docs. But all these things, like, it's so funny, we see them today, and maybe it seems we just think about, like, oh, there's the Python docs. But actually at a certain point, you know, Sphinx emerged, this concept of a how-to emerged. These are all things that over the last, I think, like, 30 years sort of, like, came into existence.

So Sphinx is like the OG doc site. A lot of tools use it. Pandas uses it to generate its APIs. Polars uses it as well. So some really big Python tools use it to generate their API docs. It uses this thing called restructured text. I will say, like, I don't know that a lot of open tool developers love it. But I do think that restructured text is kind of not the thing most open source developers are reaching for these days. But Sphinx is like the OG doc site, and it powers a ton of docs like Python.org and Pandas.

Yeah. I'm sure if, you know, I'm sure it was really made a huge improvement when it came out, though, right? If you're doing a lit tech before, that's got to be pretty rough. Yeah. It's like zero to one, essentially, I think, switching from lit tech to Sphinx for, like, your Python docs. Yeah. And if I see an RST file, just a little tear wells up in my eye. I'm like, oh, gosh, here we go. It's almost like a rite of passage, I feel like. Like, as a Python developer producing docs in the, like, Sphinx world, you just kind of, like, I learned Sphinx and RST to generate docs, essentially. It's like, yeah, I feel like that was my rite of passage into, like, software development.

Yeah. 100%. So we've also got MK docs, or make docs, probably. I don't know. I always feel like I say make docs, but I have no, I mean, you had the Zensucle people, so I feel like they, do you have a read on it? If I try to remember, I feel like Martin said MK docs, but he could have easily said make docs, and I was not paying attention. I'm a make doctor, so. Yeah, no, I think that makes sense. A lot of these that could be said one way or another, I really wish, and maybe this does, but I really wish on their GitHub repo, they just have a little mp3, like, here's how you say it. You know what I mean? A little audio button. Yeah, exactly. It's like a green unicorn, like, g-unicorn versus goonicorn is, like, one that I think goes around and around still.

Okay, so Zensucle is one of the more modern ones, so I think that that's pretty interesting. I don't, honestly, I'm not sure how much it lands in the Sphinx make docs world, or in the other, maybe the just pure static site generator side of things. The Zensucle folks came on and probably have the best sense, but my sense is it's also meant to be kind of a, it might be a drop-in replacement for make docs. Yeah, yeah, it is a compatibility, at least compatible for a material for make docs. Yeah, for sure. So, yeah, I would say it's in that realm. It also seems like they're heading towards general purpose or knowledge bases, which goes maybe a bit beyond just like- Yes, exactly. That was my, like, uncertainty is how do I classify it, right? Because it's, it doesn't even necessarily, if you look at their H2, it doesn't say the best way to make your docs, right? It's a scalable way for technical writing.

Right, which makes it, I think, land a little more in the Hugo or Ghost side of things. So, that's another part to talk about is just like static sites in general. You know, why would I choose, say, Sphinx over Hugo or Hugo over Sphinx or something like that? Yeah, it seems a bit like Mintlify. They have the same sort of thing going too. They do documentation sites, but they go a bit beyond. It's like general purpose, lots of different languages supported, but it is documentation, but not really so much like a site, like just general purpose site generator.

Right. So, Hugo and Ghost, I don't know Ghost very well, but Hugo, for example, I use that a lot for blogs. I've seen one of my friends does really cool stuff just in general with Hugo, making general purpose sites. I feel like this is much more focused on, I just need a static site and much less, I need it to read my doc strings and categorize my modules and API calls and put in that kind of stuff, right? So, that's another realm that is similar to what you all are doing, but certainly not the same. Yeah. If you want to throw another one in, there's Quarto by the company. We work at Posit, and that does sites and much more beyond.

Yeah, I had JJ on, and I'm so sorry, I'm forgetting the name of the other guy I had on. Oh, Charles. Yeah, I think it was Charles. I had to talk about Quarto a little while ago. That was fun. Yeah. I do think a lot of the questions with Hugo versus something more targeted at docs for a tool is hitting on what are the parts of a doc site? What's technical writing versus package documentation? Am I just doing a Hugo thing? Is what I'm doing similar enough to a blog or a website with content, which is really common? My website's in Hugo, or do I need something special to dump out my API docs to dump out the things from my functions and classes? Or could I jam that into Hugo? That's a common kind of- Hybrid path. Could my thing just dump my info into Hugo? It's all kind of this dance between, really, is this a general content problem? Is this a very specific tool problem? Or can I jam them both together into something?

Introducing Great Docs

Yeah, that's an interesting problem. So maybe a good time to start talking about great docs. What is it? What's its value prop and positioning with regard to these other areas? Well, on your screen, you have Packaged Down. Yes. It's an origin. It's actually coming from R. I can't help but to be a little bit influenced by Packaged Down. I use it a lot in my R projects. And it kind of felt like there was a Packaged Down-sized hole in the Python docs ecosystem, just a little bit, where you could just point something at your docs and it makes something pretty fast with pretty much no configuration. That's the challenge. Does it present something that's serviceable, usable right away? And that's what I was shooting for. And I think that's kind of where I landed. And of course, we have tons of options to do way more things. But I wanted to give something that was, you know, you just start it right away, and it gives you something. Like, for instance, you have doc strings and such, and they all just get captured and put into the API reference section. And then later on, you would attend to it and organize it and then arrange it and exclude things. At the very beginning, it would just give you something at least. So that was kind of like my goal, I think.

Yeah, the up and running super quick is one of the themes, right? Yeah. Yeah, absolutely. Yeah. Because I think, I suspect, maybe a lot of people are getting more into Python now because of agents, AI, LLMs, and such, and are spinning up small projects. And maybe they're even building their documentation sites with using the same things like LLMs. So getting something up quickly, and maybe the project doesn't last very long. It's just like a, you know, something just to get going. And you don't want to spend a ton of time on learning like the docs, a new doc system. So this sort of thing is pretty valuable. But we still give you the opportunity, of course, to, you know, like add things and do really cool, sophisticated sites. But just the up and running part, it was super important to me.

So by default, you can point it at a package or set of Python files or something and say, generate docs around that, and it will look for doc strings and so on, and then generate some kind of hierarchical? Yeah, exactly. And we tested it quite a bit on different package layouts, like, you know, different packaging systems. And it seems to introspect pretty well based on all sorts of variation. And we do test this a lot. So the promise is that it does give you something.

And you can also create just more static site type stuff as well, yeah? Yeah. Oh, absolutely. Yeah, you can. I think the user guide's a good example. Like, if you click the expandable thing in the top left. Yeah, everything's so zoomed. Yeah, everything's so zoomed on my little small streaming screen. So yeah, the user guide got it. That's, it's nice. The user guide's just a folder in the repo with files in it. But it's nice, like, that puts up this, like, yeah, more kind of general bit of content, where it's not your API reference, which is like each individual function explained, but a more general kind of guide, kind of like a bigger, higher level, like introduction to the package. But it's nice that to your point, like, can you have more general kind of content? It's nice. This is just a folder in the repo. So getting started with the user guides, like, super fast.

Yeah, and this site is, like, a demonstration. We're showing, like, the great docs site, and we're just looking at it. And you can just add another directory and, like, recipes at the top nav. That's just another directory. And we sort of declared it in our configuration file. So you can just create something similar to a user guide. But we sort of treat a user guide as a sort of, like, a first class thing. Because we, well, I'm a little bit opinionated about how sites, these docs sites should be. So it kind of serves as a model. So, like, the idea is that if someone sees this and says, yeah, I would like something like this, then, like, great docs would be a good fit. You just have to sort of emulate what we have here, do a few things, and you've pretty much got it beyond the simple sort of, like, init and then, like, build. You can just go a little bit beyond.

Sitting here talking to you makes me think, you know, I've got some open source projects. I really should have better docs with them. Maybe I'll try working on them with Great Docs. Oh, yeah. And I love your feedback. I'm always looking for like ideas and feedback. Right now, I'm not going to make a big deal of it, but I'm looking for users because it's a brand new project. So like feedback is a bit scant at this point. So yeah, let me know how it goes.

Rich features and Quarto integration

One of the things that's nice here that I'm noticing is it's got a lot of elements of the display that go beyond just standard markdown that I think are really nice. Like for example, you've got these, I guess these are probably like little tags or badges. And then also you've got a tabbed UI for like, here's how you install it on Mac, Linux, Windows, but in the same little area, right? You just like click the tab for your OS. Yeah. We call those tab sets in Quarto. They're like a Quarto special, really. They just come part and parcel with Quarto.

So yeah, I feel like you can do some nice authorship beyond that. When I was working on my book, I'm like, I'm going to write it in markdown, but I also want to have these little callouts or like an action or the little sidebar, like how in the heck am I going to get that to come out of Pandoc? And I eventually got it to work by basically getting a little pre-parser that would just turn those into HTML and allow the markdown to have HTML. I think that's what makes a good user guide, a good user guide. We actually show like, not just like show the code, but actually show the results. And you can totally do that, you know, with a good user guide. And that's what I try to demonstrate here in the Great Docs User Guide, that we have these things, here's how they look. You can have these too.

That's the one thing too with Quarto that like if I had to make the case for Quarto for a lot of people doing documentation, it's that it's really easy to run code. Running code is kind of like most of Quarto's game, that it's a, you author using a QMD. It's essentially a markdown file, but your code blocks can be executed. So it's really inconvenient for docs, like being able to include code snippets with their out, and then they get run and their outputs are there. So that's kind of the impetus, I think, in this case for Quarto is doing like really easy execution of code.

It's possible in other tools, and I know Make Doc Strings, who I think its author is working with Zensicle now too, but like they've created a lot of good ways for you to be able to do this as well, like execute code. But I do think that's one area where people stub their toe a lot is like, oh, like if I'm Polars or Pandas, I'm a DataFrame library, I probably want a lot of examples. And then you get stuck in this like funny dance, like how do I execute the code for my examples? So I think tools like Quarto are really kind of aimed at that use case, like you're a person running code and generating reports, you know, that have code and that produce graphs and tables and all that.

I think the examples, like being executable, made the great tables examples really powerful. You can see the code for a table and then see the table right below, like in the actual like site, which is, we didn't have to paste that in, it was basically just generated right there. Yeah, that's amazing. Which is actually incredible. We have pros around it as well. So it's like, it reads just like a little mini guide in each docstring.

Does it run at build time or does it somehow run in the website? Oh, build time. Yeah, yeah. But you can also... WebAssembly or something fun like that? You could do that. You could do that. Yeah. Another nice thing is you can freeze it. So like if you have a bit of code that, or like, let's say you have a blog post and you don't want to rerun it every time, because like over the years, maybe you just, you like know the code is going to get out of date or it takes a long time to run. You can do something called freeze. You can Quarto freeze it. And that essentially like caches the outputs so that you can rerender it without executing the code every time.

So that's useful. Like great tables, we have kind of a growing log of blog posts and we don't want to re-execute them every time because that starts to get pretty time consuming. So we can just freeze their outputs and then they generate super fast. Another reason you might want to freeze it is you're accessing live data off an API or a website and you want to talk about the results and if it changes, like all of a sudden your pros is like, why are you talking about this? It doesn't say that. Well, it used to when I did it. You might imagine like a benchmark section example, if it runs a long time or you're just accessing some keys on your personal machine, absolutely. Freezing is great for that.

I think there's like a million, there's also like a million of these things that you encounter when you start generating doc sites or like personal content, which is like, yeah, maybe I don't want to run some stuff. Maybe I want to like include a snippet from one thing somewhere else. Or maybe I want to do like all kinds of like output customization. I just feel like there's a million little boxes to check. So yeah, that's, that's one. I mean, one other reason we use Quarto is we belong to the company that created Quarto. But I think those like little pieces of detail for people generating like scientific documents and stuff goes a long way.

It's pretty wild too, because Quarto has a pretty big extension system as well, like pretty active. So there's like ways, I mean, besides like different output types, there's like extensions and different types of extensions too, like different classes of extensions. So it goes really deep. Yeah, Quarto is really neat. And you all keep talking about Quarto because it's the foundation of what's happening with Great Tables, right? It's been a while since it was, it's been a while since I had JJ and Carlos on the podcast to talk about Quarto. But so maybe just give folks a bit of a refresher of what is Quarto and then how that relates back to Great Tables.

Yeah. So Quarto is like an open source publishing system. So you can make things like sites, like documents, like, like books, for instance, you can make presentations. There's probably a few more I'm missing, and it's cross language as well. And like, you know, code cells. So as computational notebooks is what they call them, because they have cells, which are basically computational cells, which can accept, which have different engines. So you can, like, say, run some R code, run some Python, some Julia, what have you, many other things as well. And then you can stitch them, you know, basically render them into, into documents using Pandoc for the most part, and probably other things too, for different output types. And it just really, batteries included, has things like you just see on the site, citations, cross refs, you know, it's got it all, essentially.

And so how it relates to QuartoDoc and to Great Docs, it's, we're using QuartoDoc, it's like, but not really, like, I think with QuartoDoc, it's, you're, the way I see it is, like, correct me if I'm wrong, Michael, QuartoDoc, you're creating a reference API, but you're still basically using Quarto, you're within the Quarto itself, you're still creating the Quarto config. But with Great Docs, it's kind of like Quarto is a bit sort of like a, we're using it, obviously, but you don't have to know a lot about Quarto, you can basically get by with just a few things you see, you know, in, like, user guide, and not have to, like, go deeply into Quarto. It sort of, like, hides it a little bit, or doesn't really advertise it as much, even though we use it a lot.

Just for some context, yeah, I mentioned before, I developed a tool called QuartoDoc, which is another documentation generator for Quarto. So just to clarify, like, the context, yeah, like, QuartoDoc is a much more kind of, like, low level, no frills, so like, the Ibis project uses it. So that's another pretty, pretty big Python tool. But it's, like, very, like, simple. It's more about, like, dump your API reference, and then you're responsible for, like, customizing your website. And so it's for people who really want to, like, be in control and set it all up. I think Rich is kind of underselling, I think Great Docs is just dripping in style. So I think that's one of the keys, is it's made to be kind of, like, an all-in-one, something really nice out of the box that's opinionated. But I just wanted to clarify, for context, QuartoDoc is another tool outside of Quarto.

I think Rich is kind of underselling, I think Great Docs is just dripping in style.

So I know we've checked a lot of tools out. But I don't, one thing that's interesting is I know, like, when we look at Great Docs, it's easy to see, like, some of the stuff that jumps out. And it's really, I think to Rich's credit, there's a ton of, like, little things inside Great Docs that you almost don't notice until you need them. Like, there's a million little pieces to Docsites. And some of them are actually pretty intriguing. Like, if you go to the Great Docs API reference, I think it kind of, like, speaks to Rich's style, that he's included a ton of stuff out of the box for this, including this little, like, filter bar. So if you click on the top left, there's a, you can sort of, like, filter on the page for different pieces.

I think for, just to illustrate the difference, so QuartoDoc is a really bare-bones tool. Like, we generate an API for you. Great Docs, like, this thing, this filter bar where you can, like, type in it and it shows you live on the page, like, it filters your reference items, that's just pure Rich just, like, wilding out on what Docs could be. And I think there are, like, a million little examples of this kind of in Great Docs. Kind of, yeah, because, like, I find little things that annoy me and I want to fix them. But, and so this is my, this is almost like a Python site generator for me in lots of ways. But I'm hoping that other people feel these little pain points as well. I've certainly felt it. I've gone to documentation sites and searched for stuff on there. And then you see a little spinner, searching, searching, static site, what are we doing? Why am I waiting?

Even the CLI button, like, oh, sorry, if you click that, that's, like, if you have a command line interface for your tool, which is so hot today, like, AI loves command line interfaces. Cloud code's just bash, executing everything. You know, a lot of people have CLIs. I think it also speaks a lot to Rich's style that he created this spot for your CLI docs to live. Very important. And then at the top right, if you look, there's, like, a copy. You can copy the whole page to Markdown or view it as Markdown. I never would have thought of that. Like, to me, I would never go that far to give people something nice.

I don't know if I'm just, like, a chromogeny engineer. I think Rich is just dreaming up, like, I don't know, different ways you could interact with docs, copy the page to Markdown. And I don't doubt that it's, like, incredibly useful. To me, this strikes me as, like... I think it's very useful, yeah. When I saw that table graph for Great Tables, like, breaking apart the table into every piece, this strikes me as Rich again, like, imagining every little thing a doc site could do. So I think that's what I'm so kind of gassed up about.

AI and docs

We're going to come back to AI stuff later. But we don't have that much time left, honestly, guys. We've been talking and not making a lot of progress because it's really... Docs talk. But I can easily see I'm working on a project and I've got Claude or some codex or whatever and it's just not getting it for a certain function. Just go to the docs, hit copy pages Markdown, and just go, no, AI, this is the docs. Read it. Because giving it a Markdown result of what this is versus all the nav and all the stuff and it's trying to understand what's the essence of the page, if you tell it to just go to the page, it's really, really different. Yeah, it's a bit more immediate, I think. And also you can change the URL if you really want to to .md and just give it the URL. So many ways to do it.

So if you or Claude Code are reading the docs, you know, a lot of good stuff. Did I do that for TalkPython? I think I did. If you do that on TalkPython, by the way, you can do, just put .md on the end of any episode name and it gives you the Markdown equivalent of that as well. That's all the rage. Yeah, so I mean, we're on the same vibes here. I'm loving it. And it might even help for context. I'd be curious to hear your, like when you added that Markdown and some of your motivation for Markdownifying your site.

I didn't do it for people. I did it for AI and SEO. For the machine. Yeah, for the machine. So I added a, if I could type, I added an llms.txt to try to get the AIs to understand the podcast better. And some of the things that I gave it was this ability to just put Markdown at the end. But also I added like a CLI and an MCP and different things for an API, search API. I'm like, okay, AI. There's 7.5 million words of content over 11 years. I want you to know about it and be able to use it. How many ways can I imagine giving something to it? And this Renderer's Markdown was certainly one of them.

I also added some silly stuff that's just for me. Because I've got, for example, I've got to update, say, the YouTube recommendations. Or listings. After the live stream, I want them to have links and stuff. So I can say .youtube on the end. And it gives me the contents for the YouTube renders. So it kind of was building on this, like, how can I help myself be more efficient, but also a machine? So anyway, that's the story. It's like Docs is workflow, really, right? It fits in nicely.

So circling back around, I'm really impressed with some of these little nuances that are super nice. I think that's great. Yeah, thank you. Great Docs, that's also kind of cool. It's basically just nicing up the Docs and make them good for humans, but also consumable by LLMs or digits. Rich, it's a fad. We don't really need to worry about it. It's going to go away. The bubble's going to burst. We can just ignore it. It's going to be fine.

Getting started with Great Docs

So let's talk. I want to talk about a couple of things here. So let's just do a real quick little walkthrough of maybe getting started with this, because it's honestly not a whole lot to get started. But give us this. One of you all, walk us through the quick start, just so people know what's involved. Yeah, so really, that command, like great docs init, that'll make the file that is basically what you need for the build. And with a lot of testing, it should work on many different Python package layouts and types. So you just need that. Of course, yeah, install great docs, install Quarto as well. So we got that as well before that. But once you have those things, it should do what it says on the screen, basically show you stuff in the terminal, which is all positive. It's creating that great docs.yaml file. And it should be pretty minimal, what's in there. It should actually also be a little bit dynamic. Based on your project, it'll craft the correct great docs yaml file or the config file. And then you could go ahead and customize. But you might just jump to building your documentation, because that's the next easiest thing. It's just another command, great docs build.

And what you get is a great-docs directory in your working directory. And that contains the site folder. But you don't really have to worry about that, because you have another command called great docs preview, which will basically launch a web server and then put the site in your default browser, basically just let you see the site locally. And then because I'm a big fan of letting people know what's going on, so it should be totally a black box I give on this page, like a structure, the basic structure of how it should look in your working directory. But that's kind of it. And I believe the next step for most people will just be getting this on CI, if they're satisfied, and then just working from there, like modifying their initialization, not initialization, their config file, to give the site more customization personality. And there'll be authoring guides and things like that.

Very cool. So you've got the really nice watch feature, so great-docs-build-watch, which feels very Hugo to me. Like, you're going to build it so you can look at it, but then you want to edit it. So if you see any changes, just rebuild, right? Yeah, exactly. Small sites will build fast, but this is way faster, obviously. So yeah, this is pretty essential for iterating, especially initially, yeah. Yeah, and what about this version? So this is an interesting aspect of the project.

Versions. Well, essentially, you may have multiple tagged versions of your site, and this is kind of like a wild thing. You can have different documentation sites based on your version, because you have, for instance, new things in your API. People maybe know that from Python, where you can go up here and drop down whatever version. So this is kind of like just seeing certain versions of your site, and it gives you a selector. On the great-docs site itself, we have a selector which is maximal. It has every single version from the very first, and you can cruise in there, and you'll see that there'll be way less in the earliest versions.

If you look at the user guide for 0.1, which is a little icon, a little scary, it's saying it's unsupported. If you look at the user guide, it's pretty sparse. It's not as long as the other one. And if you look at the reference as well, it'll have less items. So it's aware of what's available in which versions. And so you sort of set that up yourself, or you can just do it through that command. Is that based on get tags, or what is that? Based on get tags, yeah, that's right. Okay, I was wondering, how does it even know? Yeah, you have to give it some information. You have to, of course, give the tags, but if you actually configure it to do what it's doing here, like make the site, you just change your configuration to have, it's basically just like a small config that you have to do. And you can set labels and things like that.

Open source sustainability

What about open source sustainability? Like, I know you all at Posit are doing a lot of things to open source your work and so on. Yeah, well, we're pretty much like full time doing open source work. So essentially, and so I think these projects have long life cycles with the same maintainer for long periods of time, which is great for project stability and things like that. And we're accountable for issues that come in and for releases and making sure it's not dead projects all the way down or whatever. So I think that's a great thing. And for instance, like Great Tables, I've been at it since the beginning, GT, which is where it came from, since 2017. So I think that helps a lot, adds a lot of credibility to these projects that are not just being abandoned. There's no fear of it being abandoned or things like that. There's a person there, at least.

Yeah, and I think Posit's found an interesting business model that's been long term sustaining, but still allows you, as you said, sort of work in open source. It's maybe speak to that, either one of you real quick. Michael, would you? Sure. Yeah, it's really interesting. And it's almost like not diving crazy deep in doing a podcast. My favorite thing to say to people is that like we have a really large open source engineering team, dozens of open source engineers. People often ask like, how does Posit pay the bills for people to work on open source? My favorite thing to say is like, we have a bunch of boring enterprise tools. And no shade on Posit, I actually think that this is the best case scenario. Like we have a lot of tools that solve really painful problems if you're an enterprise. They could be useful in other settings, but it's like, how do I run a report every day? Or how do I host like Jupyter notebooks or VS code for my, say like data team or RStudio? Those essentially pay the bills. That's Posit.

Right, right. Posit teams. You've got a team of data scientists, but you don't necessarily have a DevOps team, but you still