#549: Great Docs

Your documentation has two audiences now, humans reading the rendered HTML and AI agents making sense of your library. Rich, I known, and Michael Chow from Posit are back on Talk Python with a brand new Python documentation tool called GreatDocs that takes both seriously. Rich is the creator of Great Tables and before that, the R package GT. The man has a serious eye for design and he's pointed that energy at the Python Docs ecosystem.

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.

Yeah. 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 all 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, but in case they haven't. 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?

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.

agree with that i think it's 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 a not just the language, the tools, the ecosystem, everything. And then you're like, I'm one O, I think I have to go over there for a while.

Yeah. It feels like a bizarro situation. Like I know what I could be doing, what should be doing, like theoretically, but things just don't jive sometimes. It's like, oh, yeah. But then you, 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, a little bit sad in that regard, but you know, for me, the real challenge was I'm, 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 newbiest of noobs and it's going to feel really bad. And I was so hard for this knowledge and this experience. Why am I going to do this? Maybe I should never do that. It was really, it was a big deal for me.

Yeah, it's humbling, like I said. And well, you know, with a good venture 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.

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. I think if I had to send back what Rich is really good at, Rich just has this crazy, freaky sense of style.

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 personally am excited for the mascot. Yeah, Rich,

I blew your cover. we were yeah so michael and i were talking a little bit at pycon uh about uh tablin how you're tablin yes he hasn't been trying out a mascot wizard yeah 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 um right he hasn't fully realized he's he's he's always thinking of you he's never thinking of himself you know he's he's showing up helping you out he's like the new uh the bee or bob but

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

speaks to our dynamic where tablin just appeared one day like well while we were preparing a pi con 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 you know it's like having a pet like a cat i love it it's really good so michael

we had the great opportunity to meet up at pycon just last week i know 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 you know but it was really fun and maybe just give us your thoughts on pycon and how'd that go.

Yeah. Yeah. It's a great question. I, um, 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. Um,

I think my first one, when was my first? Mid-teens, I would say 2015, 2016, something like that. Yeah, nice. 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. And 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.

All day. Yeah. Yeah, for real. I feel like it is. Just putting the face behind the name or actually like touching down to chat does seem like a huge thing that you only do like say once or twice a year. Yeah.

With those folks. Yeah. At least for me, I can come back and revitalize to do more. So that's really, really sweet. Let's start our journey here. Talking about, just do a quick review of Great Tables. Because I know Great Tables was one of the inspirations for Great Docs. So we all both got together, 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 many people know this, 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.

Yeah, that's awesome. What strikes me about this, 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, oh gosh, I can't remember the guy's name, but I'm sure you both have seen his books. But it's... Is it Stephen Peavy? Tufty? No, no, no. Tufty. Tufty, yes. Okay. He's just like, oh, I see.

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 where you can communicate data in a better way in a 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

or a better way to do it yeah there's you could just look at certain types of presented information and you go, well, that looks really professional or that looks really, really good, but I don't know why. You know what I mean? Yeah. This looks bad. That was good, but I don't, yes, but I can't put my hand or 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 Tufti principle too, 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 a lot of that that goes into this.

Indeed.

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.

Yeah, I think it's really out there. Like initially when I did too, it was 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.

I remember I was talking about that. Yeah. How interesting is it? Yeah. How interesting is it that the inspiration comes from pre-digital times? Yeah. And I think that, yeah, because a lot of the software reduces 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.

Yeah. Yeah. And it's like, I was like searching, like researching, like anything on tables I could find just to get ideas and like, you know, like what people thought was good. And it's really hard to find anything on tables. It was like, oh, but I did find that one thing. And like, I'm forever in debt to the person who wrote it.

Yeah, that's awesome. This portion of Talk Python To Me is brought to you by Sentry. You know Sentry for their great error monitoring, but let's talk about logs. Logs are messy. Trying to grep through them and line them up with traces and dashboards just to understand one issue isn't easy. Did you know that Sentry has logs too? And your logs just became way more usable. Sentry's logs are trace connected and structured, so you can follow the request flow and filter by what matters.

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 QuarterDoc. 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 experience looking at the history of Python docs. I think Sphinx is one of the OG site builders. I think this is the case.

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

you're doing a look at before that's got to be yeah 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 it's

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

passage i feel like as a python developer producing docs in the like sphinx world you just kind of like you learn i learned sphinx and rst to generate docs essentially uh it's like yeah i feel like that was my rite of passage into like software development 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 no i i have no so i mean you had the zensical people so i feel like they do you have a read on it if i try to remember i

like martin said mk docs but whoa i i not he could have easily said make docs and i was not paying attention yeah um i'm a doctor so yeah no i think that 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 little audio button yeah exactly it's like a green unicorn like g unicorn versus goonicorn is

side of things i mean the sensical folks came on and probably have the best sense but um my sense is it's also meant to be kind of a i might be wrong drop-in replacement for make docs i know

their community yeah yeah it is a it is a um compatibility at least compatible uh for a material for make docs yeah right right right yeah for sure so yeah i would say it's in that 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 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 um thing so that's another part to part to talk about it's just like static sites in general you know why would i choose say sphinx over hugo or

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 uh but it is documentation but not really so much

like a site like just general purpose site generator so it's so hugo and ghost i don't know goes 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

Yeah, if you want to throw another one in, there's Korto by the company we work at, Posit, and that does sites and much more beyond.

I do think I had JJ on and I'm so sorry, I'm forgetting the name of the other guy. Oh, Charles. Yeah, I think it was Charles. Oh, cool. To talk about Korto a little while ago. That was fun.

Yeah. I do think a lot of the questions with like Hugo versus something more targeted at like docs for a tool is hitting on kind of like, what are the parts of a doc site? You know, like what's technical writing versus like package documentation? Am I just doing a Hugo thing? Like is what I'm doing similar enough to like a blog or a website with content, which is really common, like my website's in Hugo?

Yeah, that's an interesting problem. So maybe a good time to start talking about, you know, great docs. What is it? Like, what's its value prop and positioning with regard to these other areas?

Well, on your screen, you have package down. Yes. It has an origin. Actually, coming from R, I can't help but to be a little bit influenced by package down. I use it a lot in my R projects. And I kind of felt like there was like a package downsized hole in the Python docs ecosystem, just a little bit, where, you know, you can just point something at your docs and it makes something pretty fast with pretty much no configuration. That's like the challenge.

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

Yeah, yeah, absolutely. 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 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 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 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.

It's nice, the user guide's just a folder in the repo with files in it. But it's nice like that 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.

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 doc sites should be.

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

Maybe.

Maybe I'll try working on them with great docs. That would be really fun. Oh, yeah.

And I love your feedback. I'm always looking for ideas and feedback. Right now, I'm not going to make a big deal of it. But I'm looking for users because this is a brand new project. So feedback is a bit scant at this point. So yeah, let me know how it goes.

Yeah, I will definitely. 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 oh because these are probably like little tags or badges yeah 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 because tab sets in cordo

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

you can do some nice authorship beyond that. Like 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 call outs or like an action or, you know, the little sidebar, like how in the heck am I going to get that to come out of Pandoc? You know what I mean? Yeah. 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 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, that definitely looks good. That's the one thing too with Quarto that 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. 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.

and that produce graphs and tables and 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 incredibly you can put pros around it as well so it's like it reads just like a little mini guide in each doc string does it

run at build time or does it somehow run in the website oh build time yeah yeah yeah you guys embedding WebAssembly or something fun like that no you could do that you could do that yeah i

another nice thing you can freeze it so like if you have a bit of code that um 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 like know the code's going to get out of date or it takes a long time to run. You can do something called freeze. You can quarter 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.

Another reason you might want to freeze it is you're doing 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. Well, it used to when I did it. You might imagine like a benchmark section example

if it runs a long time or you just, you know, 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. high.

And 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 that's, that's one.

It's pretty wild too, because Kordo 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. This portion of Talk Python To Me is sponsored by Temporal. Ever since I had Mason Egger on the podcast for episode 515, I've been fascinated with durable workflows in Python. That's why I'm thrilled that Temporal has decided to become a podcast sponsor since that episode. If you've built background jobs or multi-step workflows, you know how messy things get with retries, timeouts, partial failures, and keeping state consistent.

and then how that relates back to great tables um yeah so cordo is a like a like open source publishing system so you can make things like sites um like documents like books for instance uh you can make presentations uh it's probably a few more i'm missing and it's cross language as well and it and like you know code cells so it has computational notebooks is what they call them because they have cells which are basically computational cells which can accept

even though we're using a lot. Just for some context. Yeah. I mentioned before I developed a tool called QuarterDoc, which is another documentation generator for Quarto. So just, just to clarify like the context. Yeah. Like QuarterDoc 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.

Kind of. Yeah. Cause like I find little things that annoy me and I want to fix them. But, um, uh, and so this is my, this is almost like a, like a, like a Python site generator for, for me in lots of ways, but I'm hoping that other people feel these little pain points as well.

I've certainly felt I've gone to, um, documentation sites and search 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.

Yeah.

Yeah.

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 codes just bash executing everything. You know, a lot of people have CLIs. I think it also speaks a lot to Richestile 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.

This is delightful. And 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, we're just diving into it. Docs talk. It's so fun. I know. It's so fun. 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.

Yeah, it's been more immediate, I think. 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 it said html.md. Yeah. Yeah.

That's really cool. So if you were plot code or reading the docs, you know, a lot of good stuff.

Yeah, season tokens. Yeah, yeah, yeah. That's cool. Did I do that for Talk Python? I think I did. Yeah. You do that on Talk Python, by the way. You can just put.md on the end of any episode name, and it gives you the markdown equivalent 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 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 the machine stuff yeah for the machine so um i 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 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.

It's like Doc's workflow really, right? It fits in nicely.

You know, circling back around, I'm really impressed with some of these little nuances that are super nice. I think that's great. Great talks. If you want to go further on this,

it's basically just nicing up the docs and make them good for humans, but also consumable by LLMs or agents and such.

Rich, it's a fad. We don't really need to worry about it. It's going to go away. It'll pass, yeah. The bubble's going to burst. 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. 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 Porto 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.

You've got the really nice watch feature. So great docs build --watch. Yes. 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 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. 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, 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.

Right. People maybe know that from Python where you can go up here and drop down. Exactly. Like version selectors.

So this is kind of like just seeing like certain versions of your site and it gives you a selector. On the GreatDocs 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 gives a little icon, a little scary saying it's unsupported. If you look at the user guide, it's pretty sparse.

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. Like you have to, of course, get the tags, but if you actually configure it to do what'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.

Can I wildcard it or have it somehow pick up all the versions? I mean, you don't want to pick up all tags, but it'd be like star dot star.

I don't think we have version expressions like that yet. Yeah.

Not yet. Okay.

You know, throw it in there.

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

Yeah, you probably wouldn't do it through like this interface, like Great Docs build. This is just for like a pretty quick comparison. But if you would do it, like you probably put that in the config file and you'd have to manually edit those. But I think with a slot or something like that would be better.

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

it's kind of, you wouldn't do this, but it's just, I threw it in there.

Well, probably because your commands use that, right? Yeah, exactly. Might as well just let people know that.

Just being transparent.

I suppose. Yeah. Where do we want to go next? Let's, let's cover just a couple, couple of remaining things here while we're, we got time to have, 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 like long life cycles with the same maintainer for long periods of time, which is great for project stability and things like that. And like, you know, we're accountable for like, you know, issues that come in and for, you know, releases and making sure, you know, it's not, you know, like dead projects, you know, like all the way down or whatever.

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. Michael, we're joking.

Yeah, it's really interesting. And it's almost like not diving crazy deep and doing a podcast. My favorite thing to say to people is that we have a really large open source engineering team, dozens of open source engineers. People often ask, how does Posit pay the bills for people to work on open source? And my favorite thing to say is like, we have a bunch of boring enterprise tools and I'm no shade on pause. I actually think that this is the best case scenario.

You've got a team of data scientists, but you don't necessarily have a DevOps team, but you still want to have their stuff running reliably, right?

Yeah, and it's a hard problem. If you're a company, right, these are kind of tricky problems. Or you have like a really mean IT team. A cruel IT team could hamstring you for years. But that's just to say we get to work on open source because these tools exist. And I think Posit exists, I think, because the maintainers care so much about open source. I will say in terms of sustainability, one interaction I've really liked over the years is like in the docs realm, there's this person.

A hundred percent agree. Very cool. Now, Rich, you mentioned that pretty new project. Yeah. Where are we going? What's on the roadmap?

Yeah, lots of things. I even have a roadmap on the site if anyone's interested. But I think it'll be like a lot more like documentation for different things, like new things. Like the other day, I was suggested to create documentation for MCP servers. I was like, good idea. We don't really have that. And it's pretty easy to document JSON, essentially. So we can take that apart, parse that, and present something.

that's a good point because if you look at the mcp servers they don't have structure in the way that traditional projects do right they don't just have like a separate function for each thing they've got this kind of weird invocation entry point where you pass like the tool you want to use and yeah it's

documentation suggestions things like that uh so i think we could do a pretty good job there that's the idea is pretty new but like i guess we're yeah just trying to be where or go where things are

going and be a little bit ahead so would that somehow show itself as like where you've got the um the api and the cli would there also be an mcp or what do you think it's gonna be a bit crowded so i'm rethinking i know yeah yeah i was like i don't really know this would be it like but no

that's not quite it there's you know maybe one or two more things uh so it might be just a drop down nav on the top like a drop down on the top nav so that's part of the part of like uh what i have to think about. But there's things like that. And also like a recent thing we just did, and this is very new, so it's almost like it's new enough, is like skills, like publishing skills and making them available and making them browsable, right? So on the very, it's not top level.

So we're trying to make that a bit easier. Yeah, it's super cool. Yeah, it's super cool. Yeah, that kind of brings me to the last thing that I wanna talk about is the AI-ification. And by that, I don't mean, How do I, are you using AI to write it or not?

Yeah, we looked at this closely, yeah.

Putting, yeah, so did I, and I find it super interesting. Like this, the idea is that if you, you know, there's a robots.txt and a sitemap.xml. These are standard web things on sites that humans rarely use to get any value from, but machines and traditionally search engines really, really do. And so, well, what do we put for AI to make it better, LLMs and so on? is this llms.txt file that describes in Markdown to the LLMs, like how you can better work with this.

This one's interesting. It's a lot. So basically it's the entire bit of documentation distilled down, not distilled, but like written as one file, essentially. All doc strings mashed together, you might say, including guide material as well. So that's all in there.

Yeah, and you've got these skills as well, which is looking super interesting and also a pretty neat, the CLI that you've created a couple of things on that. First of all, that it will actually install the skills.

Yeah. So if you're an author, you would just use great docs, install, skill install, and then they may be the name of your library for other people. That's what other people would see on their sites.

That's an interesting piece. Cause if I'm an, I have to admit, I haven't seen the skills piece a lot, but if I'm understanding rich too, this means great docs is also for like kind of all users, right? Like people who are interested in reading or consuming docs or using it with AI. Is that right? I see. So that's kind of where we're going more and more.

Yeah. So it looks like you're really leaning into making great docs, something that works well if you're trying to generate docs and maintain with AI, right?

We also want, if you point your agent at this site, it should be able to find these things pretty quickly. And you can actually like use tools. Like there's one called whatdoagentsc.runtime.app. Just search it up. You can put it in your URL and it'll show you what pieces are picked up by different agents. It actually simulates it really nicely. And I found that this sort of validated things that different agents do pick up LLMs.txt, LLMs.full.

Very exciting. I love it. Okay. And also just you mentioned that there's the CLI, right? Or I don't know what I was mentioning. But the fact that there is a CLI is another really great enablement. 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. Here's the docs and the skill. Make this happen. You know, right? Yeah.

Yeah. And you can even, the skills I include, like in great docs could be used to author your own great doc site. Like there's all sorts of things in there for like just how it works and like, you know, like, like writing pages, they're kind of split up into like multiple name skills.

So you can, you can just use that or make your own skills. Yeah. Very neat. All right. Two really quick things. I know we're pretty much out of time for you guys. One, what I get out of this is just a static site and I can just host it on any static site place. Okay. That's really good. For sure. it could be netlify it could be you know pages for me on provide some fine grained instructions

for different uh hosts and things like that github pages like seems like a nice default it's not you know but of course yeah netlify versal things like that we provide some hints

that it works for me i i was running on netlify for a while but i actually had my monitoring software monitoring it and it actually went down surprisingly often i'm like why is my static site going down this makes no sense so i've ended up recently i've already got like a big server with tons of sites so i just i'll just have a config on nginx that just runs it you know and so there's

a lot of options there yeah it's so interesting not not to dwell on it but i do remember you saying i think on a podcast with um hugo talking about your hugo van anderson your approach that you're you have way less downtime than even some of the cloud providers so not not to go too deep

that's interesting to hear about let's it is i i could go for hours on this so be careful there michael i find it really interesting that you just the extreme simplicity of like i've got a server and either it's got a self-contained python and database runtime or it's just even a static site that goes a long ways you know really long ways instead of like all the 100 connected services powered by some dynamic thing underneath. And if one of them goes down, it takes a chunk with it.

Yeah, yeah, for sure.

Maybe that was my last question. I think just the deployment side of things is really interesting. So it sounds like just wherever, right? Anything that serves static files, you get to go.

Pretty much, yeah. Because you get the site directory and you just go with that. Like it's complete site in a directory.

Yeah, okay. So the second, now I remember, the second thing I wanted to talk about was if I go over to the user guide and I do a quick start, You show me the structure and I get this here, this yourprojectgreatdocs.aml, greatdocs, et cetera, et cetera. So it looks like the recommendation is to have great docs as a sub directory of your actual things that it is documenting. Is that right? Sort of, but you don't have to keep it.

I mean, like it's just going to appear there when you render locally and you can look at the site, you can preview it, but you can just delete it. I can have it on CI or whatever, like on your CI system or however you're deploying.

Like your step could be build and then copy and then delete. Yeah, exactly. The folder, not necessarily the YAML. Well, yeah, you want to keep that.

Yeah, yeah, that's config. So that, commit that. And hopefully I sort of like outlined it here on this page, what should be like, you know, committed. And we automatically .gitignore some things too. So you don't accidentally commit things. You don't have to.

If I want to do the freeze though, I probably have to keep it. Yeah.

No, we actually work around that. So we do like a, like a pre. We got a little system there. So I know it wipes everything out, but we have a freeze mechanism that sort of works around this sort of like ephemeral nature of things. Yeah, still uses coral freeze. So it just does it a little bit different.

Yeah, very interesting. Okay, final thoughts. People are interested in this. They want to get started. What do you tell them?

Yeah, just check out the site. I'm hoping you'll be not wowed, but that it will resonate a little bit and the site should demonstrate what's possible. And again, like, you know, Even just like have your agent, like, you know, like have some AI, take a small Python package of yours and see what it could do. Take it for a little spin. And if there's anything that you think is missing or lacking, just drop me a line, like through the issues. That's like, that's basically it.

Can I publish on read, read the docs?

I don't think we have that yet. Yeah. I actually never even considered that as a, as a publishing point.

One of the standard places to put docs, not necessarily required, but it's, it'd be interesting, you know?

Okay. I'm going to log that down. That's already like, that's a good one.

All right. We're rewriting the roadmap live here.

Yeah. That's a toughie. You threw down the gauntlet, you know, this is it.

Sounds good. Well, I really appreciate you both being here. Michael, you want to have a final word as well of inspiration for folks? What a great question.

I, my, my final nudge might be like, we talked a lot about generating docs, the kind of technical activity. I do think there's this world of how do you write docs? Like what should your content be? And what should your sections of your doc site be? Obviously we're saying goodbye. So that's, we don't want to open that can of worms. But I just wanted to cast a light on that. That is a freaky big area on its own. I don't have great answers. So I'm just throwing some problems on people's laps.

I think what you're doing is you're setting the stage for another episode in the future. Yeah, that's right.

We're just trying to make it a three, you know, like a trilogy. So we're trying to get our third visit in.

Perfect. All right. Well, Rich, Michael, thanks for being here. It's great as always. Thanks so much for having us. Yeah. Bye. Thanks. This has been another episode of Talk Python To Me. Thank you to our sponsors. Be sure to check out what they're offering. It really helps support the show. This episode is brought to you by Sentry. You know Sentry for the error monitoring, but they now have logs too.

We tapped into that modern vibe overcame each storm.

Talk Python To Me. I sync is the norm. Продолжение следует...