Transcript#

This transcript was generated automatically and may contain errors.

Rich, Michael, welcome back to Talk Python to Me. Yeah, thanks for having us. Yeah, for sure. We're going to talk about great things. 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. 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, PVC. 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. 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.

I think it's hard to change a language. It's hard to switch to another language. 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, I'm 1.0. 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. And then your previous language degrades. 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? It was a big deal for me.

Yeah, it's humbling, like I said. And well, 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.

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 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. 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. And I think if I had to send back 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 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 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. Like 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 style and design into tools.

Introducing Tablin and PyCon reflections

Yeah, that's really cool. Certain people just have a knack for APIs and the way that developer UX sort of thing. That's cool. I personally am excited for the mascot. Rich, I blew your cover. So Michael and I were talking a little bit at PyCon about Tablin, how you're a mascot wizard. Who is Tablin, though, I wonder? He's just a little table guy, a little table dude, that appears, gives you help, and then disappears just as fast. He doesn't fully realize that. He's always thinking of you. He's never thinking of himself. He's showing up, helping you out. He's like the new Libby or Bob, but much cooler because he's a table.

And I do think this speaks to our dynamic where Tablin just appeared one day. While we were preparing a PyCon talk two years ago, Tablin just appeared in the slides, and I didn't know who Tablin was. 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.

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. Maybe just 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 funny point you can always talk to anyone about at PyCon. But I find it really nice and I find the PyCon organizers and the Python Software Foundation, it's just so down to earth. It doesn't feel super corporate. It feels like they're really a group of passionate volunteers putting this pretty big conference on. So yeah, I always love dropping in, even if it's a broader audience than the data crew.

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. Just putting the face behind the name or actually touching down to chat does seem like a huge thing that you only do like, say, once or twice a year with those folks. Yeah, at least for me, I can come back and revitalize to do more. So that's really, really sweet.

Great Tables revisited

Let's start our journey here talking about, let's just do a quick review of Great Tables. Because I know Great Tables was one of the inspirations for Great Docs. 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 maybe not being people notice, it's a port of an R package called gt. Not that important, but the idea is 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, 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 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 changing orders, adding cell backgrounds, things like that. And really, the idea is to make a table that you might see in a print publication, but using your data directly, using a data frame.

You know, when we had our conversation last year, it's 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... is his name Tufty? Tufty, yes. He's just like, oh, I see, like there's some lines and stuff. Like, 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. No, you don't even have to call it out. It's communicated through something more interesting.

Yeah, it's pretty well. We talked about this in our talk a few years back in PyCon, how you can tell a story with a table, where you can communicate data in a better way. Not a more optimized way, but a more legible way, where your main point is described 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, or a better way to do it.

We talked about this in our talk a few years back in PyCon, how you can tell a story with a table, where you can communicate data in a better way, not a more optimized way, but a more legible way, where your main point is described like a title and a subtitle, and you have notes at the bottom.

Yeah, there's this funny thing called the stubhead and spanners, and I thought, like, does a person really need to know all this? But I think to the point of Tufty, like maybe what you're getting at, too, is Tufty 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 axis 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, like if you're looking at stocks, you'll have like the stock numbers, and then you'll have a spark line that like indicates the kind of trend. But I find what's interesting about Tufty is just that willingness to dive in so detailed about this one very specific action. At first, I wasn't really convinced. It seemed like a lot of work, but yeah, I think to your point about Tufty, 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, 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 it's 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.

Yeah, how interesting is it that the inspiration comes from pre-digital times? Yeah, because a lot of the software produces some of these ideas. It's like, well, I have grids. I have a grid of cells, and sometimes the rows can be taller. Sometimes you can span a row. Okay, that's that. But if you just write it by hand, when you have to way back in the day, it's like, oh, well, maybe we could draw it differently, right?

Surveying the documentation landscape

So let's move on. But if people are out there, and they're doing presentations that involve tables, and especially if it's code generating those tables, check this out. It's quite interesting. So the next thing I want to talk about is just surveying the landscape of what is out there. Because we're going to talk about great docs, and great docs can generate static sites. There's some existing tools that generate docs as static sites. There's some really good tools that just generate static sites that maybe people could put into docs. There's a lot of things that are somewhat similar. I know you all have mentioned Sphinx is a real popular one in the Python space. There's mkdocs. 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, I worked a lot on early support for documentation with a tool called QuartoDoc. But Rich actually took it to the next level. And this goes to, I think, Rich's style with great docs. So I have a lot of bizarre, like, experience looking at the history of Python docs. And I think Sphinx is one of the OG site builders. 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. 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.

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 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.

I'm sure it was really made a huge improvement when it came out, though, right? If you're doing a lot of tech before, that's got to be pretty rough. Yeah. It's like zero to one, essentially, I think, switching from the 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 mkdocs, or mkdocs, probably. I say mkdocs, but I have no... so, I mean, you had the Zensicle people, so I feel like they... Do you have a read on it? If I try to remember, I feel like Martin said mkdocs, but... 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. Yeah, exactly. Like, green unicorn, like, g-unicorn versus goonicorn is, like, one that I think goes around and around still.

So, Zensicle is one of the more modern ones. So, I think that that's pretty interesting. And also like a recent thing, and this is very new, kind of a, it might be a drop-in replacement for mkdocs. Yeah, yeah, it is a compatibility, at least compatible for a material for mkdocs. 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 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, 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 to, 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 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. I do think, 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. 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, 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 pkgdown. Yes, it's an origin. It actually comes from R. I can't help but to be a little bit influenced by pkgdown. I use it a lot in my R projects. And it kind of felt like there was a pkgdown sized hole in the Python docs ecosystem, just a little bit, where you can 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 just start it right away and it gives you something.

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 my goal, I think.

Yeah, the up and running super quick is one of the themes, right? Yeah, absolutely. Because 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 something just to get going. And you don't want to spend a ton of time on learning the docs, a new doc system. So this sort of thing is pretty valuable. But we still give you the opportunity, of course, to 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 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. Yeah, I think the user guide's a good example. 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. Getting started with the user guide's 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, 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.

Yeah, 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, maybe I'll try working on them with great docs. That would be really fun. Right now, I'm not gonna 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.

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. Yeah, they're actually tags, right. Yeah, 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. Like, when I was working on my book, I'm like, I want to write it in markdown, but I also want to have these little callouts or, like, an action or, you know, the little sidebar. 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.

Yeah, yeah, that definitely looks good. 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, 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 MakeDocStrings, 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, or if 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? And 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.

Yeah, and 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. You can put 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, at build time. But you can also — WebAssembly or something fun like that? No. 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's gonna 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 re-render 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 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. Like, well, it used to when I did it. Yeah, 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. You basically froze stuff on your personal computer and you're just like, you know, sending it off to like CI.

And I think there's 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 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. And it's pretty wild too, because Quarto has a pretty big extension system as well, like pretty active. So there's like ways, besides like different output types, there's like extensions and different types of extensions to like different classes of extensions. So it goes really deep. Yeah, Quarto is really neat.

What is Quarto?

And you all keep talking about Quarto because it's the foundation of what's happening with Great Docs, right? 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 Docs.

Yeah, so Quarto is like an open source publishing system. So you can make things like sites, like documents, like books, for instance. You can make presentations. And it's cross-language as well. And like code cells. So it has 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, like 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 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 all essentially.

And so how it relates to QuartoDoc and to Great Docs, we're using Quarto as like, you know, but not really. Like I think with QuartoDoc, it's the way I see it is like, and 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 the 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.

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 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 wanna 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. 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. So I know we've checked a lot of tools out, but 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, but there's actually, 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.

I think Great Docs is just dripping in style. 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.

Like there's a million little pieces to doc sites 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, you can sort of like filter on the page for different pieces. That's like, yeah. I think for just to illustrate the difference, so QuartoDoc is a really bare bones tool. It's 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. And so 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? This doesn't make any sense to me, but okay.

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 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.

When I saw that table graph for Great Tables, like breaking apart the table into every little 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. Yeah, that's delightful.

And we're gonna come back to AI stuff later, 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. Yeah, yeah, yeah, I love that. So instead of html.md. Yeah. Yeah, that's really cool. So if you, you or Claude Code are reading the docs, you know, a lot of good, a lot of good stuff. Yeah, here's some tokens.

Did I do that for TalkPython? I think I did. Yeah, 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. So which is all the rage. Yeah, so I mean, we're on the same vibes here. I'm loving it, you know what I mean? Yeah, 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 stuff. Yeah, for the machine.

So I added a, I did 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. And 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 render as markdown was certainly one of them. That's great. Yeah, that's awesome.

I also added some silly stuff that's like for, just for me, because I've got, for example, I've got to update, say, the YouTube recommendations. So, or listings after the live stream, I want them to have like links and stuff. So I can say .youtube on the end, and it gives me the contents for like 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. This is where it's like Doc's workflow really, right? Fits in nicely.

Getting started with Great Docs

So, you know, 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. I'll go further on this. It's basically just nicing up the docs and make them good for humans, but also consumable by LLMs or digits. It's just, 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, we can just ignore it. It's going to be fine.

No. So let's talk, I want to talk about a couple of things here. So let's just do like 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 kind of 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 like Python package, like 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 like 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 hyphen docs directory in your working directory. And that contains like 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 like a web server and then put the site in your default browser, basically just like 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 on 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 config file to give the site more customization personality.

So you've got the really nice watch feature. So great docs build dash dash watch. Yes. Which feels very Hugo to me, you know, like you're gonna build it so you can look at it, but then you wanna edit it. So just 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.

And what about this version? So this is an interesting aspect of the project. Versions. Well, essentially you may have, you know, 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. Cause you have, for instance, new things in your API. Right. People maybe know that from Python where you can go up here and drop down. Exactly. So this is kind of like just seeing like 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 like 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.

Like the, if you look at the user guide for 0.1, which is a little icon, a little scary. It's unsupported. If you look at the user guide, it's pretty sparse. Like it's, you know, it's not as long as the other one. So it's aware of like 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 git tags or what is that? Based on git tags. Yeah, that's right. Okay. I was wondering how does it even know? Yeah, you have to give it some information. Like you have to of course get 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

Let's cover just a couple of remaining things here while we got time. 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, to sort of work in open source. 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 connected to Posit teams. You've got a team of data scientists, but you don't necessarily have a DevOps team, but you still wanna have their stuff running reliably, right?