#549: Great Docs

WEBVTT
00:00:00.020 --> 00:00:02.300
Your documentation has two audiences now,
00:00:02.480 --> 00:00:05.320
humans reading the rendered HTML and AI agents making
00:00:05.560 --> 00:00:06.460
sense of your library.
00:00:06.680 --> 00:00:07.680
Rich, I known,
00:00:07.900 --> 00:00:10.960
and Michael Chow from Posit are back on Talk Python with a
00:00:10.970 --> 00:00:15.180
brand new Python documentation tool called GreatDocs that takes both seriously.
00:00:15.620 --> 00:00:16.700
Rich is the creator of
00:00:16.760 --> 00:00:18.320
Great Tables and before that,
00:00:18.500 --> 00:00:19.460
the R package GT.
00:00:19.670 --> 00:00:22.160
The man has a serious eye for design and he's pointed
00:00:22.210 --> 00:00:24.240
that energy at the Python Docs ecosystem.
00:00:24.620 --> 00:00:27.500
We'll talk about how GreatDocs spins up a polished site
00:00:27.540 --> 00:00:28.300
and three commands,
00:00:28.500 --> 00:00:32.040
why every page ships as markdown for your favorite LLM,
00:00:32.220 --> 00:00:32.980
how it leans
00:00:33.080 --> 00:00:36.200
on Quarto for executable code blocks and tabbed install sections,
00:00:36.780 --> 00:00:37.620
and where it lands against
00:00:37.780 --> 00:00:38.120
Sphinx,
00:00:38.440 --> 00:00:38.900
MkDocs,
00:00:39.180 --> 00:00:39.620
and Zensical.
00:00:39.820 --> 00:00:40.180
Plus,
00:00:40.380 --> 00:00:42.680
you'll meet Tablin. Here we go. This is Talk Python To Me,
00:00:42.840 --> 00:00:43.840
episode 549,
00:00:44.200 --> 00:00:45.200
recorded May 19th,
00:00:45.600 --> 00:00:46.380
2026.
00:01:05.160 --> 00:01:09.480
Welcome to Talk Python To Me, the number one Python podcast for developers and data scientists.
00:01:10.030 --> 00:01:10.740
This is your host,
00:01:10.920 --> 00:01:11.380
Michael Kennedy.
00:01:11.580 --> 00:01:15.320
I'm a PSF fellow who's been coding for over 25 years.
00:01:15.960 --> 00:01:17.020
Let's connect on social media.
00:01:17.480 --> 00:01:19.660
You'll find me and Talk Python on Mastodon, Bluesky,
00:01:20.020 --> 00:01:20.540
and X.
00:01:20.840 --> 00:01:22.660
The social links are all in your show notes.
00:01:23.420 --> 00:01:26.940
You can find over 10 years of past episodes at talkpython.fm.
00:01:27.120 --> 00:01:30.320
And if you want to be part of the show, you can join our recording live streams.
00:01:30.680 --> 00:01:31.140
That's right.
00:01:31.400 --> 00:01:34.600
We live stream the raw uncut version of each episode on YouTube.
00:01:35.200 --> 00:01:39.520
Just visit talkpython.fm/youtube to see the schedule of upcoming events.
00:01:39.860 --> 00:01:43.480
Be sure to subscribe there and press the bell so you'll get notified anytime we're recording.
00:01:44.060 --> 00:01:48.020
Hey friends, before we dive in, I want to share something I just launched over at Talk Python,
00:01:48.340 --> 00:01:48.960
a new course.
00:01:49.380 --> 00:01:51.460
If you ship Python to production,
00:01:51.780 --> 00:01:53.680
you've probably had that quiet thought about
00:01:54.060 --> 00:01:55.680
what might be lurking in your code.
00:01:55.920 --> 00:01:59.160
My new course turns that worry into a concrete workflow
00:01:59.440 --> 00:02:02.380
and a reusable AI security agent that's yours forever.
00:02:02.760 --> 00:02:04.440
It's Python Web Security,
00:02:04.600 --> 00:02:06.780
the OWASP top 10 with agentic AI.
00:02:07.720 --> 00:02:11.440
Check it out at talkpython.fm/AI dash web dash security.
00:02:11.560 --> 00:02:13.960
The link is in your podcast player and on the episode page,
00:02:14.220 --> 00:02:16.000
or just go to talkpython.fm
00:02:16.220 --> 00:02:17.520
and click on courses at the top.
00:02:17.780 --> 00:02:18.660
It should be right there.
00:02:19.220 --> 00:02:23.180
So if you're interested in making sure the apps and APIs that you ship are secure,
00:02:23.560 --> 00:02:24.160
this
00:02:24.160 --> 00:02:24.780
is the course for you.
00:02:25.520 --> 00:02:27.080
This episode is brought to you by Sentry.
00:02:27.840 --> 00:02:29.240
You know Sentry for the error monitoring,
00:02:29.540 --> 00:02:30.840
but they now have logs too.
00:02:31.200 --> 00:02:31.720
And with Sentry,
00:02:32.140 --> 00:02:33.840
your logs become way more usable,
00:02:34.360 --> 00:02:36.340
interleaving into your error reports
00:02:36.470 --> 00:02:38.200
to enhance debugging and understanding.
00:02:38.740 --> 00:02:41.960
Get started today at talkpython.fm/sentry.
00:02:42.740 --> 00:02:44.500
And it's brought to you by Temporal,
00:02:44.660 --> 00:02:46.120
durable workflows for Python.
00:02:46.560 --> 00:02:50.920
Write your workflows as normal Python code and Temporal ensures they run reliably,
00:02:51.600 --> 00:02:53.180
even across crashes and restarts.
00:02:53.760 --> 00:02:56.500
Get started at talkpython.fm/Temporal.
00:02:57.460 --> 00:02:57.980
Rich, Michael,
00:02:58.340 --> 00:03:00.060
welcome back to Talk Python To Me.
00:03:00.410 --> 00:03:02.100
Awesome to have you both back on the show.
00:03:02.440 --> 00:03:03.340
Yeah, thanks for having us.
00:03:03.780 --> 00:03:04.840
We're going to talk about great things.
00:03:05.230 --> 00:03:06.460
I know it's going to be a great show.
00:03:06.710 --> 00:03:07.240
It's undoubtable,
00:03:07.420 --> 00:03:07.480
right?
00:03:08.140 --> 00:03:09.040
I have no doubt.
00:03:09.220 --> 00:03:09.840
It's a great day,
00:03:10.060 --> 00:03:10.320
you know,
00:03:10.500 --> 00:03:11.300
and we're ready for,
00:03:11.860 --> 00:03:12.680
I think what's going to be a
00:03:12.880 --> 00:03:13.620
great chat.
00:03:13.880 --> 00:03:14.000
Yeah.
00:03:14.740 --> 00:03:16.160
About great docs,
00:03:16.480 --> 00:03:16.960
great tables,
00:03:17.280 --> 00:03:18.100
all of those things.
00:03:18.460 --> 00:03:19.080
All the great things.
00:03:19.280 --> 00:03:19.680
Yeah.
00:03:20.100 --> 00:03:22.000
So I had you on to talk about great tables,
00:03:22.540 --> 00:03:23.340
which was really fun.
00:03:23.600 --> 00:03:24.800
You all both from Posit.
00:03:25.400 --> 00:03:25.780
And
00:03:26.260 --> 00:03:29.020
other than that, maybe let's do a quick introduction for folks.
00:03:29.520 --> 00:03:30.820
I mean, I don't know why anybody would
00:03:31.020 --> 00:03:32.800
not have listened to the great tables episode,
00:03:33.180 --> 00:03:35.080
but in case they haven't. No, we honestly,
00:03:35.160 --> 00:03:36.880
we get a bunch of new listeners all the time.
00:03:37.120 --> 00:03:40.080
So yeah, let's do a quick round of introductions.
00:03:40.230 --> 00:03:40.640
Who are you?
00:03:40.850 --> 00:03:42.880
What do you do? Why are you working on this project?
00:03:43.140 --> 00:03:43.300
Rich,
00:03:43.520 --> 00:03:43.840
start with you.
00:03:44.150 --> 00:03:44.280
Yeah.
00:03:44.730 --> 00:03:44.860
Yeah.
00:03:45.080 --> 00:03:45.400
I'm Rich.
00:03:45.880 --> 00:03:46.800
I work at Posit,
00:03:47.260 --> 00:03:47.460
PBC.
00:03:48.000 --> 00:03:49.920
I've been doing traditionally lots of R stuff,
00:03:50.310 --> 00:03:50.920
like in the past,
00:03:51.190 --> 00:03:51.680
but more lately,
00:03:51.880 --> 00:03:53.520
this is like the last three or four years,
00:03:53.820 --> 00:03:54.740
a lot more Python
00:03:55.020 --> 00:03:55.140
stuff.
00:03:55.500 --> 00:03:56.760
And actually Michael,
00:03:57.120 --> 00:03:58.040
who's with me today,
00:03:58.350 --> 00:03:59.260
he taught me a lot about Python.
00:03:59.620 --> 00:04:00.120
Like I was
00:04:00.590 --> 00:04:01.400
pretty bad starting.
00:04:01.600 --> 00:04:04.040
I mean, I used in the past, but I was open source stuff. I was,
00:04:04.360 --> 00:04:09.840
oh that was bad michael has so much patience though so uh he'll make up speed over a period
00:04:09.870 --> 00:04:15.680
of a year or so um so i owe a lot to him and yeah that's he's a great guy that's really cool i i
00:04:16.180 --> 00:04:21.540
agree with that i think it's it's hard to change a language it's hard to switch to another language
00:04:21.670 --> 00:04:26.860
and maybe you could speak to that real quick before michael jumps in and just i've done that a couple
00:04:26.920 --> 00:04:32.320
times you know you spend so much time and energy and effort and getting really good at a not just
00:04:32.320 --> 00:04:32.680
the language,
00:04:32.880 --> 00:04:33.800
the tools, the ecosystem,
00:04:33.980 --> 00:04:34.220
everything.
00:04:34.680 --> 00:04:37.600
And then you're like, I'm one O, I think I have to go over there for a while.
00:04:37.920 --> 00:04:38.160
Yeah.
00:04:38.180 --> 00:04:39.340
It feels like a bizarro situation.
00:04:39.560 --> 00:04:40.900
Like I know what I could be doing,
00:04:41.100 --> 00:04:41.540
what should be doing,
00:04:41.920 --> 00:04:42.560
like theoretically,
00:04:43.040 --> 00:04:43.460
but things just
00:04:43.580 --> 00:04:44.220
don't jive sometimes.
00:04:44.600 --> 00:04:45.080
It's like, oh,
00:04:45.400 --> 00:04:45.520
yeah.
00:04:45.660 --> 00:04:49.000
But then you, then you get used to it and then your previous language degrades.
00:04:49.920 --> 00:04:50.980
It's kind of like that sort of thing.
00:04:51.480 --> 00:04:54.660
It's a little bit, a little bit sad in that regard, but you know, for me,
00:04:54.900 --> 00:04:55.360
the real challenge
00:04:55.480 --> 00:04:55.800
was I'm,
00:04:56.200 --> 00:04:59.880
I have such a deep knowledge and mastery of this technology.
00:05:00.440 --> 00:05:01.340
And if I switch,
00:05:01.820 --> 00:05:08.420
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.
00:05:08.540 --> 00:05:12.620
And I was so hard for this knowledge and this experience.
00:05:13.260 --> 00:05:15.080
Why am I going to do this?
00:05:15.400 --> 00:05:16.340
Maybe I should never do that.
00:05:16.380 --> 00:05:17.900
It was really, it was a big deal for me.
00:05:18.320 --> 00:05:18.900
Maybe you could just,
00:05:19.100 --> 00:05:24.260
I want to say that for other people out there who are not necessarily going R to Python, but just one tech to another.
00:05:24.600 --> 00:05:25.240
Yeah, it's humbling,
00:05:25.560 --> 00:05:25.960
like I said.
00:05:26.000 --> 00:05:27.040
And well,
00:05:27.460 --> 00:05:27.620
you know,
00:05:27.860 --> 00:05:29.420
with a good venture and lots of patience,
00:05:30.200 --> 00:05:30.660
it can happen.
00:05:31.120 --> 00:05:32.240
Yeah, it's good to expand your skills,
00:05:32.440 --> 00:05:34.180
but the initial decision is rough.
00:05:34.540 --> 00:05:34.860
Michael,
00:05:35.200 --> 00:05:37.960
you've been shepherding Rich along the way.
00:05:38.000 --> 00:05:38.440
I love it.
00:05:38.720 --> 00:05:39.260
Tell us about yourself.
00:05:39.620 --> 00:05:43.560
I wouldn't even say shepherding, or maybe there's like some mutual shepherding going on.
00:05:44.080 --> 00:05:45.300
So I'm Michael Chow.
00:05:45.560 --> 00:05:50.560
I'm a software engineer at Posit and have been for about four years on the open source team.
00:05:51.020 --> 00:05:51.100
Yeah.
00:05:51.220 --> 00:05:51.620
And I,
00:05:52.100 --> 00:05:53.820
so I've worked with Rich on things like great tables.
00:05:54.440 --> 00:05:55.100
And I think that,
00:05:55.560 --> 00:05:56.920
yeah, I'm really interested in Python.
00:05:57.020 --> 00:05:58.340
I work on Python full time.
00:05:59.700 --> 00:06:03.120
I think if I had to send back what Rich is really good at,
00:06:03.900 --> 00:06:05.500
Rich just has this crazy,
00:06:05.760 --> 00:06:06.640
freaky sense of style.
00:06:07.000 --> 00:06:11.660
And I think that's one thing that's drawn me to work with him on things is you just never know.
00:06:12.180 --> 00:06:13.040
Like, to be totally honest,
00:06:13.420 --> 00:06:15.980
people at Posit just never know what Rich is going to pull out.
00:06:16.260 --> 00:06:18.600
And I don't think any of us could have imagined it.
00:06:18.740 --> 00:06:19.000
He's a loose,
00:06:19.240 --> 00:06:19.980
he's our wild card.
00:06:21.080 --> 00:06:23.980
And it's been interesting because you can imagine like a programming language.
00:06:24.580 --> 00:06:26.720
Yeah, you could be like, oh, this person taught me this programming language.
00:06:27.080 --> 00:06:28.900
I don't really know how you teach Rich's style,
00:06:29.120 --> 00:06:32.180
but I feel like I'm kind of along for the ride. I'm like eating popcorn,
00:06:32.600 --> 00:06:37.160
helping out. And I think tools like Great Docs really reflect that, this interesting sense of style.
00:06:37.340 --> 00:06:37.800
Great tables.
00:06:38.220 --> 00:06:42.020
He's just dipped into this rich history of table styling.
00:06:42.300 --> 00:06:46.080
How would you style it to present and maybe publish it?
00:06:46.380 --> 00:06:55.360
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.
00:06:55.660 --> 00:06:55.960
Yeah,
00:06:56.160 --> 00:06:56.700
that's really cool.
00:06:57.280 --> 00:06:57.560
You know,
00:06:57.840 --> 00:07:02.360
certain people just have a knack for APIs and the way that develop,
00:07:02.520 --> 00:07:04.340
you know, the developer UX sort of thing.
00:07:04.460 --> 00:07:04.760
That's cool.
00:07:05.080 --> 00:07:07.580
I personally am excited for the mascot.
00:07:08.060 --> 00:07:08.180
Yeah,
00:07:08.360 --> 00:07:08.980
Rich,
00:07:09.160 --> 00:07:11.660
I blew your cover.
00:07:12.080 --> 00:07:18.100
we were yeah so michael and i were talking a little bit at pycon uh about uh tablin how you're
00:07:18.260 --> 00:07:24.180
tablin yes he hasn't been trying out a mascot wizard yeah who is tablin though i wonder he's
00:07:24.180 --> 00:07:29.380
just a little table guy a little table dude that appears gives you help and then disappears just
00:07:29.390 --> 00:07:34.400
as fast um right he hasn't fully realized he's he's he's always thinking of you he's never thinking
00:07:34.430 --> 00:07:40.059
of himself you know he's he's showing up helping you out he's like the new uh the bee or bob but
00:07:40.080 --> 00:07:45.380
much cooler because he's a table and can display things this absolutely yeah and i do think this
00:07:45.500 --> 00:07:50.240
speaks to our dynamic where tablin just appeared one day like well while we were preparing a pi
00:07:50.280 --> 00:07:56.040
con talk two years ago tablin just appeared in the slides and i didn't know who tablin was and i was
00:07:56.100 --> 00:08:01.080
like who or what is this it was like a slide of a table and tablin was popped out on the side was
00:08:01.180 --> 00:08:05.959
saying good job and i was like who's this spreadsheet with eyes and a mouth cheering
00:08:05.980 --> 00:08:10.760
people on and rich was like it's tablin of course yeah it's helpful to have a little dude that just
00:08:10.880 --> 00:08:17.720
wants to help you know it's like having a pet like a cat i love it it's really good so michael
00:08:18.040 --> 00:08:23.160
we had the great opportunity to meet up at pycon just last week i know i don't know how you feel
00:08:23.220 --> 00:08:28.800
about it personally i'm still just a little bit recovering from the whole energy that was extracted
00:08:29.060 --> 00:08:33.959
from me you know but it was really fun and maybe just give us your thoughts on pycon and how'd that
00:08:33.840 --> 00:08:33.880
go.
00:08:34.140 --> 00:08:34.360
Yeah.
00:08:34.840 --> 00:08:35.900
Yeah. It's a great question.
00:08:36.120 --> 00:08:36.240
I,
00:08:36.740 --> 00:08:37.039
um,
00:08:37.520 --> 00:08:40.140
it's so interesting because we work on tools for
00:08:40.300 --> 00:08:40.820
data analysis,
00:08:41.580 --> 00:08:44.980
but PyCon is much more general. It's almost like all things Python.
00:08:45.410 --> 00:08:45.800
I think it's
00:08:45.800 --> 00:08:51.500
a really interesting conference versus like a PyData or a SciPy, which are way oriented towards
00:08:51.690 --> 00:08:53.260
like data tools specifically.
00:08:53.840 --> 00:08:54.120
Um,
00:08:54.520 --> 00:08:57.180
but I love it. I find it really nice to be able to drop in and
00:08:57.340 --> 00:09:03.800
talk to just the full range of Python people who maybe have never used or done a lot of data
00:09:04.640 --> 00:09:08.600
So I find it really interesting to talk to folks who maybe almost universally, I think
00:09:08.840 --> 00:09:11.620
everybody has touched pandas, the library for data frames.
00:09:12.200 --> 00:09:17.060
And so that's the like funny kind of like point you can always talk to anyone about at
00:09:17.200 --> 00:09:17.420
PyCon,
00:09:17.880 --> 00:09:19.380
but I find it really nice.
00:09:19.380 --> 00:09:24.740
And I find the like PyCon organizers and the sort of Python software foundation,
00:09:25.320 --> 00:09:25.540
it's just
00:09:25.540 --> 00:09:26.960
so down to earth that,
00:09:27.360 --> 00:09:29.040
yeah, I really love dropping in.
00:09:29.040 --> 00:09:30.720
It doesn't feel super corporate.
00:09:31.240 --> 00:09:37.040
It feels like they're really like a group of passionate volunteers putting this like pretty big conference on.
00:09:37.300 --> 00:09:37.380
So,
00:09:37.680 --> 00:09:37.740
yeah,
00:09:37.930 --> 00:09:39.180
I always love dropping in,
00:09:39.740 --> 00:09:44.020
even if it's like a kind of broader audience than the like data crew.
00:09:44.440 --> 00:09:45.480
I'm curious your experience.
00:09:45.700 --> 00:09:47.020
Have you gone to a lot of PyCons?
00:09:47.290 --> 00:09:48.500
I think my first one,
00:09:48.920 --> 00:09:49.680
when was my first?
00:09:50.000 --> 00:09:51.760
Mid-teens,
00:09:52.090 --> 00:09:53.200
I would say 2015,
00:09:53.620 --> 00:09:54.220
2016,
00:09:54.760 --> 00:09:55.220
something like that.
00:09:55.500 --> 00:09:55.700
Yeah,
00:09:55.860 --> 00:09:56.020
nice.
00:09:56.480 --> 00:09:58.980
I'd probably have gone to maybe two thirds since then.
00:09:59.340 --> 00:09:59.460
Most.
00:09:59.900 --> 00:10:01.020
I mean, we did have COVID in the middle.
00:10:01.110 --> 00:10:02.180
That was challenging.
00:10:02.620 --> 00:10:03.040
But yeah,
00:10:03.240 --> 00:10:05.580
I've been to a fair number and I really enjoy it.
00:10:05.580 --> 00:10:08.520
And for me, it's just nice to get together,
00:10:09.160 --> 00:10:10.780
meet folks like you and everyone else and
00:10:10.810 --> 00:10:11.840
just kind of remember,
00:10:12.020 --> 00:10:15.060
hey, this is a community of humans and not just docs.
00:10:15.560 --> 00:10:15.880
Never mind.
00:10:15.960 --> 00:10:16.160
I mean,
00:10:16.460 --> 00:10:16.880
docs are great.
00:10:16.940 --> 00:10:18.340
We're going to talk about how great docs can be.
00:10:18.460 --> 00:10:23.200
But it's also nice to just have these human connections and just connect with people outside
00:10:23.760 --> 00:10:24.480
of with,
00:10:24.640 --> 00:10:26.080
but also outside of technology,
00:10:26.400 --> 00:10:26.460
right?
00:10:26.600 --> 00:10:26.680
Like,
00:10:27.020 --> 00:10:28.700
let's just go sit in the sun for a while and talk.
00:10:29.000 --> 00:10:30.260
Like, have you seen The Sun lately?
00:10:30.340 --> 00:10:31.180
No, I haven't seen it either.
00:10:31.300 --> 00:10:31.840
Let's go sit there.
00:10:32.260 --> 00:10:32.680
All day.
00:10:33.140 --> 00:10:33.240
Yeah.
00:10:33.620 --> 00:10:34.160
Yeah, for real.
00:10:34.260 --> 00:10:35.180
I feel like it is.
00:10:35.620 --> 00:10:40.080
Just putting the face behind the name or actually like touching down to chat does seem like
00:10:40.080 --> 00:10:43.980
a huge thing that you only do like say once or twice a year.
00:10:44.420 --> 00:10:44.480
Yeah.
00:10:44.500 --> 00:10:45.140
With those folks.
00:10:45.640 --> 00:10:45.720
Yeah.
00:10:45.900 --> 00:10:48.660
At least for me, I can come back and revitalize to do more.
00:10:48.840 --> 00:10:49.880
So that's really, really sweet.
00:10:50.320 --> 00:10:52.660
Let's start our journey here.
00:10:54.020 --> 00:10:57.740
Talking about, just do a quick review of Great Tables.
00:10:58.080 --> 00:11:00.840
Because I know Great Tables was one of the inspirations for Great Docs.
00:11:00.920 --> 00:11:03.020
So we all both got together,
00:11:03.260 --> 00:11:04.900
all three of us got together last year,
00:11:05.100 --> 00:11:05.440
I guess,
00:11:05.760 --> 00:11:06.760
to talk about Great Tables.
00:11:07.140 --> 00:11:10.520
So who wants to just do a quick reminder of this one?
00:11:11.699 --> 00:11:12.300
I'll go.
00:11:13.120 --> 00:11:13.460
So basically,
00:11:13.980 --> 00:11:14.620
yeah, Great Tables,
00:11:15.200 --> 00:11:15.400
it's a,
00:11:15.580 --> 00:11:17.640
maybe not many people know this,
00:11:17.680 --> 00:11:19.320
it's a port of an R package called GT.
00:11:20.000 --> 00:11:23.540
Not that important, but the idea is good as it was then.
00:11:24.120 --> 00:11:25.220
You want display tables,
00:11:25.760 --> 00:11:26.540
what I call them.
00:11:26.660 --> 00:11:32.060
essentially summary tables like static tables and you want to present them say in a notebook or say
00:11:32.200 --> 00:11:38.220
like in some other publishable document as html we also have a latex output format but the idea is
00:11:38.220 --> 00:11:43.860
you compose tables step by step you know you add a header you want you want a title you get that too
00:11:44.280 --> 00:11:50.420
you structure the table you can format different cells like usually entire columns of cells or and
00:11:50.620 --> 00:11:55.719
you can also style a table which could be like you know like changing orders adding cell backgrounds
00:11:55.780 --> 00:11:56.360
things like that.
00:11:56.880 --> 00:12:00.320
And really the idea is to like to make a table that you might see like in a print
00:12:00.440 --> 00:12:00.640
publication,
00:12:01.600 --> 00:12:02.400
but using your data,
00:12:02.780 --> 00:12:03.160
like directly,
00:12:03.360 --> 00:12:04.060
like using a data frame.
00:12:04.330 --> 00:12:05.560
So you have the data in
00:12:05.560 --> 00:12:08.820
a form which is amenable to a summary table.
00:12:09.200 --> 00:12:12.120
And then in just a few like method calls,
00:12:12.600 --> 00:12:13.040
you've got
00:12:13.040 --> 00:12:13.360
the table.
00:12:14.440 --> 00:12:14.880
Yeah,
00:12:15.360 --> 00:12:15.740
that's awesome.
00:12:15.920 --> 00:12:17.280
What strikes me about this,
00:12:18.000 --> 00:12:19.980
when we had our conversation last year,
00:12:20.280 --> 00:12:26.880
It's just how much more there is to think about with tables than, you know, just an Excel-like thing.
00:12:27.180 --> 00:12:31.280
I came away realizing that it goes way deeper and there's a lot more nuance.
00:12:31.800 --> 00:12:37.640
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.
00:12:37.880 --> 00:12:38.300
But it's...
00:12:38.940 --> 00:12:39.760
Is it Stephen Few?
00:12:40.140 --> 00:12:40.460
Tufte?
00:12:40.540 --> 00:12:40.740
No,
00:12:40.940 --> 00:12:41.240
no, no.
00:12:41.520 --> 00:12:41.800
Tufte.
00:12:42.220 --> 00:12:42.700
Tufte, yes.
00:12:43.160 --> 00:12:43.280
Okay.
00:12:43.580 --> 00:12:44.500
He's just like, oh,
00:12:44.670 --> 00:12:44.980
I see.
00:12:45.120 --> 00:12:46.720
Like there's some lines and stuff like, no, no, no, no.
00:12:47.000 --> 00:12:47.460
Hold on.
00:12:47.820 --> 00:12:48.900
There's a lot going on.
00:12:49.020 --> 00:12:49.140
And like,
00:12:49.860 --> 00:12:54.980
there's many things you can communicate subtly without just being like, well, let's just call this out.
00:12:55.050 --> 00:12:56.540
Like, no, you don't even have to call it out.
00:12:56.660 --> 00:12:59.840
It's communicated through something more interesting.
00:13:00.920 --> 00:13:05.500
You know, a tough thing is that about just presenting sort of scientific information in general.
00:13:05.700 --> 00:13:07.360
But I felt that way about tables as well.
00:13:07.620 --> 00:13:08.460
Yeah, it's pretty well.
00:13:08.530 --> 00:13:11.360
We talked about this in our talk a few years back in PyCon.
00:13:12.700 --> 00:13:17.940
how like you can tell a story with a table where you can communicate data in a better way in a
00:13:18.580 --> 00:13:23.420
not a more optimized way but a more legible way where like your main point is like describe like
00:13:23.420 --> 00:13:29.280
a title and a subtitle and you have notes at the bottom and you can guide people through an analysis
00:13:29.480 --> 00:13:33.480
summary that way and so just like with many different things there's a good way to do it
00:13:33.820 --> 00:13:38.839
or a better way to do it yeah there's you could just look at certain types of presented information
00:13:38.860 --> 00:13:39.500
and you go,
00:13:39.690 --> 00:13:41.140
well, that looks really professional
00:13:41.290 --> 00:13:42.280
or that looks really,
00:13:42.460 --> 00:13:42.980
really good,
00:13:43.360 --> 00:13:44.160
but I don't know why.
00:13:44.560 --> 00:13:45.140
You know what I mean?
00:13:45.420 --> 00:13:45.600
Yeah.
00:13:45.720 --> 00:13:46.320
This looks bad.
00:13:46.670 --> 00:13:47.900
That was good, but I don't, yes,
00:13:48.140 --> 00:13:50.780
but I can't put my hand or my finger
00:13:50.920 --> 00:13:52.420
on exactly what is really different,
00:13:52.920 --> 00:13:54.580
but that's really good and that's not, you know?
00:13:54.630 --> 00:13:57.560
And I feel like Great Tables kind of leans into that.
00:13:57.800 --> 00:13:59.980
Yeah, I guess it takes the Tufte principle too,
00:14:00.200 --> 00:14:01.780
like having just the right amount of ink,
00:14:02.060 --> 00:14:02.300
I guess,
00:14:02.400 --> 00:14:03.100
like not too much,
00:14:03.300 --> 00:14:04.100
just enough to communicate
00:14:05.130 --> 00:14:05.980
the structure of things,
00:14:06.080 --> 00:14:10.700
like the sort of like the architecture of the data you're laying out and not doing much more than that.
00:14:10.970 --> 00:14:12.900
So there's a lot of that that goes into this.
00:14:13.290 --> 00:14:13.400
Indeed.
00:14:13.760 --> 00:14:14.420
As a default thing.
00:14:14.590 --> 00:14:15.880
To the Tufte point too,
00:14:16.500 --> 00:14:17.100
Tufte's website,
00:14:17.340 --> 00:14:20.480
Tufte has like all of these just dumps of examples,
00:14:20.940 --> 00:14:22.200
just like example plot,
00:14:22.420 --> 00:14:23.260
example plot, example plot.
00:14:23.290 --> 00:14:24.960
It's almost like a very rough notebook.
00:14:25.490 --> 00:14:26.780
And I feel like with great tables,
00:14:27.450 --> 00:14:28.220
it was kind of similar.
00:14:28.450 --> 00:14:32.680
Like when I first came on, I knew basically nothing about this topic.
00:14:33.160 --> 00:14:36.180
And I saw the components of the table diagram.
00:14:36.410 --> 00:14:37.240
So you have it pulled up,
00:14:37.470 --> 00:14:40.440
but it has like a table broken apart into all its pieces,
00:14:40.700 --> 00:14:40.760
like
00:14:40.760 --> 00:14:41.140
a title,
00:14:41.680 --> 00:14:42.200
subtitle.
00:14:42.560 --> 00:14:45.400
There's this funny thing called the stub head and spanners.
00:14:46.140 --> 00:14:46.720
And I thought like,
00:14:47.050 --> 00:14:49.260
does a person really need to know all this?
00:14:49.720 --> 00:14:53.280
But I think to the point of Tufte, like maybe what you're getting out to is Tufte really
00:14:53.500 --> 00:14:55.620
dives into like very specific,
00:14:56.190 --> 00:14:58.880
almost like dimensions of how you could represent data.
00:14:59.320 --> 00:15:01.340
One thing he gets really into is like sparklines,
00:15:01.600 --> 00:15:06.320
this idea that like how far could you get with a line that basically doesn't have any axis labels,
00:15:06.960 --> 00:15:07.980
but it's just like a trend.
00:15:08.530 --> 00:15:10.200
Like is it going up or is it going down?
00:15:10.550 --> 00:15:11.640
And that happens a lot in tables.
00:15:11.920 --> 00:15:14.620
You'll put like these sparklines in a cell.
00:15:15.020 --> 00:15:16.040
Like if you're looking at stocks,
00:15:16.600 --> 00:15:22.760
you'll have like the stock numbers and then you'll have a sparkline that like indicates the kind of trend so people can grab it really fast.
00:15:23.140 --> 00:15:30.040
But I find what's interesting about Tufte is just that willingness to dive in so detailed about this one very specific action.
00:15:30.580 --> 00:15:33.400
And I feel like this table diagram is sort of similar to me,
00:15:33.580 --> 00:15:36.480
the willingness to break it apart so thoroughly.
00:15:36.940 --> 00:15:38.500
At first, I wasn't really convinced.
00:15:38.890 --> 00:15:40.380
It seemed like a lot of work.
00:15:40.740 --> 00:15:42.300
But yeah, I think to your point about Tufte,
00:15:42.460 --> 00:15:50.500
once you start looking at examples, you start to realize this kind of captures the flavor or design of good examples out there in the world.
00:15:50.800 --> 00:15:50.960
Yeah,
00:15:51.290 --> 00:15:52.500
I think it's really out there.
00:15:52.830 --> 00:15:55.180
Like initially when I did too, it was like, oh, this is too much.
00:15:55.490 --> 00:15:56.480
But naming things is so important.
00:15:56.620 --> 00:15:59.560
Otherwise, you're just awkwardly describing something over and over again,
00:15:59.960 --> 00:16:00.700
like that cell
00:16:00.710 --> 00:16:03.120
to the top left or these cells off to the side.
00:16:03.440 --> 00:16:05.020
And eventually you just have to give it a name,
00:16:05.280 --> 00:16:06.380
even if it's not the best name.
00:16:06.630 --> 00:16:12.120
And these are actually names I stole from like basically a census manual on tables,
00:16:12.660 --> 00:16:13.840
I think written in 1949.
00:16:14.380 --> 00:16:14.680
Great ideas,
00:16:15.080 --> 00:16:16.080
like wonderful book.
00:16:16.300 --> 00:16:19.140
And it's on the web as a PDF still.
00:16:19.550 --> 00:16:20.240
It's a scam.
00:16:20.260 --> 00:16:21.560
I remember I was talking about that.
00:16:21.700 --> 00:16:21.880
Yeah.
00:16:21.880 --> 00:16:22.820
How interesting is it?
00:16:23.200 --> 00:16:23.320
Yeah.
00:16:23.420 --> 00:16:28.240
How interesting is it that the inspiration comes from pre-digital times?
00:16:28.740 --> 00:16:28.820
Yeah.
00:16:29.060 --> 00:16:29.580
And I think that,
00:16:29.800 --> 00:16:30.340
yeah,
00:16:30.600 --> 00:16:34.480
because a lot of the software reduces some of these ideas.
00:16:34.760 --> 00:16:36.040
It's like, well, I have grids.
00:16:36.370 --> 00:16:39.340
I have a grid of cells and sometimes the rows can be taller.
00:16:39.860 --> 00:16:41.080
Sometimes you can span a row.
00:16:41.410 --> 00:16:41.500
Okay.
00:16:41.900 --> 00:16:42.340
That's that.
00:16:42.640 --> 00:16:45.800
But if you just write it by hand when you have to way back in the day,
00:16:46.180 --> 00:16:46.440
it's like, oh,
00:16:46.540 --> 00:16:46.620
well,
00:16:47.060 --> 00:16:48.120
maybe we could draw it differently,
00:16:48.340 --> 00:16:48.440
right?
00:16:48.660 --> 00:16:48.940
Yeah.
00:16:49.260 --> 00:16:49.360
Yeah.
00:16:49.560 --> 00:16:50.620
And it's like, I was like searching,
00:16:51.010 --> 00:16:51.560
like researching,
00:16:51.760 --> 00:16:53.080
like anything on tables I could find
00:16:53.190 --> 00:16:54.580
just to get ideas and like, you know,
00:16:54.640 --> 00:16:56.100
like what people thought was good.
00:16:56.410 --> 00:16:57.720
And it's really hard to find anything on tables.
00:16:58.010 --> 00:16:59.800
It was like, oh, but I did find that one thing.
00:17:00.020 --> 00:17:00.380
And like,
00:17:00.540 --> 00:17:03.520
I'm forever in debt to the person who wrote it.
00:17:03.700 --> 00:17:04.400
Yeah, that's awesome.
00:17:06.439 --> 00:17:07.660
This portion of Talk Python To Me
00:17:07.689 --> 00:17:08.720
is brought to you by Sentry.
00:17:09.140 --> 00:17:11.260
You know Sentry for their great error monitoring,
00:17:11.699 --> 00:17:12.640
but let's talk about logs.
00:17:13.180 --> 00:17:14.000
Logs are messy.
00:17:14.560 --> 00:17:16.420
Trying to grep through them and line them up
00:17:16.540 --> 00:17:19.520
with traces and dashboards just to understand one issue
00:17:19.540 --> 00:17:20.100
isn't easy.
00:17:20.660 --> 00:17:22.800
Did you know that Sentry has logs too?
00:17:23.060 --> 00:17:25.339
And your logs just became way more usable.
00:17:25.900 --> 00:17:28.339
Sentry's logs are trace connected and structured,
00:17:28.720 --> 00:17:31.120
so you can follow the request flow and filter by
00:17:31.280 --> 00:17:31.760
what matters.
00:17:32.440 --> 00:17:35.240
And because Sentry surfaces the context right where you're debugging,
00:17:35.600 --> 00:17:36.760
the trace relevant logs,
00:17:36.980 --> 00:17:37.360
the error,
00:17:37.860 --> 00:17:40.500
and even the session replay all land in one timeline.
00:17:41.040 --> 00:17:42.080
No timestamp matching,
00:17:42.400 --> 00:17:43.100
no tool hopping.
00:17:43.680 --> 00:17:45.100
From front end to mobile to back end,
00:17:45.340 --> 00:17:45.860
whatever you're debugging,
00:17:46.080 --> 00:17:48.560
Sentry gives you the context you need so you can fix
00:17:48.600 --> 00:17:49.860
the problem and move on.
00:17:50.400 --> 00:17:52.640
More than 4.5 million developers use Sentry,
00:17:52.960 --> 00:17:53.600
including teams at
00:17:53.800 --> 00:17:59.320
Anthropic and Disney+. Get started with Sentry logs and error monitoring today at talkpython.fm
00:17:59.520 --> 00:18:00.420
slash Sentry.
00:18:00.620 --> 00:18:03.080
Be sure to use our code, talkpython26.
00:18:03.500 --> 00:18:05.320
The link is in your podcast player show notes.
00:18:05.820 --> 00:18:07.300
Thank you to Sentry for supporting the show.
00:18:09.220 --> 00:18:11.860
Let's move on, but if people are out there and
00:18:11.900 --> 00:18:13.780
they're doing presentations that involve tables,
00:18:14.220 --> 00:18:16.020
and especially if it's code generating those
00:18:16.020 --> 00:18:16.160
tables.
00:18:16.700 --> 00:18:17.060
Check this out.
00:18:17.480 --> 00:18:18.340
It's quite interesting.
00:18:18.690 --> 00:18:20.220
So the next thing I want to talk about is just
00:18:20.480 --> 00:18:23.860
sort of surveying the landscape of what is out there,
00:18:24.220 --> 00:18:26.140
because we're going to talk about great
00:18:26.460 --> 00:18:29.420
docs and great docs can generate static sites.
00:18:29.830 --> 00:18:32.480
So there's some existing tools that generate docs
00:18:32.800 --> 00:18:36.720
as static site. There's some really good tools that just generate static sites that maybe people
00:18:36.900 --> 00:18:40.780
could put into docs. Like there's a lot of things that are somewhat similar.
00:18:41.000 --> 00:18:41.560
There's also stuff
00:18:41.740 --> 00:18:45.020
that's in the same space, but different. So maybe we could kind of go through and,
00:18:45.300 --> 00:18:45.980
you know, like
00:18:46.000 --> 00:18:50.000
I know you all have mentioned Sphinx is a real popular one in the Python space.
00:18:50.860 --> 00:18:51.660
There's MKDocs.
00:18:52.140 --> 00:18:55.280
I had Martin from Zensical on not too long ago.
00:18:55.460 --> 00:18:58.520
So maybe we could talk first about some of the existing tools that are,
00:18:58.700 --> 00:19:01.360
I guess, as similar as possible to what you're doing.
00:19:01.680 --> 00:19:01.940
Yeah.
00:19:02.840 --> 00:19:04.480
Michael, would you like to speak on this?
00:19:04.480 --> 00:19:06.820
Because I know you did a deep dive recently on these.
00:19:07.020 --> 00:19:07.280
Yeah.
00:19:08.100 --> 00:19:08.780
So Sphinx,
00:19:09.240 --> 00:19:09.540
I think,
00:19:09.760 --> 00:19:14.000
and maybe to kick off some helpful context to great docs is that, yeah,
00:19:14.140 --> 00:19:18.280
I worked a lot on early support for documentation with a tool called quartodoc.
00:19:18.580 --> 00:19:20.900
But Rich actually took it to the next level.
00:19:21.050 --> 00:19:24.680
And this goes to, I think, Rich's style with great docs.
00:19:25.200 --> 00:19:29.520
So I have a lot of bizarre experience looking at the history of Python docs.
00:19:30.940 --> 00:19:34.220
I think Sphinx is one of the OG site builders.
00:19:36.190 --> 00:19:37.680
I think this is the case.
00:19:38.120 --> 00:19:41.960
So I think one interesting fact is, as I understand it, I think Python.org,
00:19:42.320 --> 00:19:42.960
don't quote me on this.
00:19:43.120 --> 00:19:46.480
I think it was originally done in like LaTeX or something like that,
00:19:46.820 --> 00:19:47.580
the Python docs.
00:19:48.160 --> 00:19:51.400
And I think that they moved to Sphinx at some point.
00:19:52.740 --> 00:19:55.620
So like Sphinx has a really interesting history in Python.
00:19:55.860 --> 00:19:57.380
Like if you go back 25,
00:19:57.800 --> 00:19:58.220
30 years,
00:19:58.760 --> 00:20:01.020
Python docs had to exist using some tool,
00:20:01.360 --> 00:20:01.500
right?
00:20:01.620 --> 00:20:08.160
And at some point Sphinx emerged as kind of like this dominant site builder for Python and Python docs.
00:20:09.140 --> 00:20:09.880
Yeah, does it say?
00:20:10.200 --> 00:20:10.320
Yeah.
00:20:10.740 --> 00:20:12.800
So Python docs are in Sphinx.
00:20:13.960 --> 00:20:19.000
you know this python doc site has a how-to python how-tos this is another weird fact
00:20:19.490 --> 00:20:25.580
the how-tos emerged I don't remember exactly when they emerged it was like in the last 30 years I
00:20:25.740 --> 00:20:33.960
think as part of the Linux project so the term how-to as I understand it emerged in the Linux
00:20:34.120 --> 00:20:39.880
docs but all these things like it's so funny we see them today and and maybe it seems we just
00:20:39.840 --> 00:20:40.420
think about like,
00:20:40.580 --> 00:20:40.700
oh,
00:20:40.940 --> 00:20:41.780
there's the Python docs,
00:20:42.240 --> 00:20:44.120
but actually at a certain point,
00:20:44.480 --> 00:20:44.580
you know,
00:20:44.760 --> 00:20:45.000
Sphinx
00:20:45.120 --> 00:20:45.580
emerged,
00:20:45.920 --> 00:20:47.520
this concept of a how-to emerge.
00:20:47.820 --> 00:20:49.800
These are all things that over the last, I think like
00:20:50.120 --> 00:20:53.280
30 years sort of like came into existence.
00:20:53.840 --> 00:20:55.600
So Sphinx is like the OG doc site.
00:20:56.260 --> 00:20:57.040
A lot of tools
00:20:57.580 --> 00:20:57.760
use it.
00:20:57.920 --> 00:21:00.440
Pandas uses it to generate its APIs.
00:21:01.980 --> 00:21:03.220
Polars uses it as well.
00:21:03.500 --> 00:21:04.659
So some really big
00:21:04.860 --> 00:21:11.460
python tools use it to generate their um api docs um it uses this thing called restructured text
00:21:11.900 --> 00:21:18.940
i will say like i don't know that a lot of open tool developers i love love it um i'm going to be
00:21:18.940 --> 00:21:24.620
a bit careful here because i think it's been so useful but i do think that restructured text is
00:21:24.720 --> 00:21:30.600
kind of not the thing most open source developers are reaching for these days um but sphinx is like
00:21:30.520 --> 00:21:37.140
the og uh doc site and it powers a ton of docs like python.org and pandas i'm sure if you know
00:21:37.200 --> 00:21:41.880
i'm sure it was really made a huge improvement when it came out though right yeah i think if
00:21:41.940 --> 00:21:47.220
you're doing a look at before that's got to be yeah yeah it's like zero to one essentially i think
00:21:47.660 --> 00:21:53.000
switching from lit tech to sphinx for like your python docs yeah and if i see an rst file it's
00:21:53.040 --> 00:21:58.340
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
00:21:58.340 --> 00:22:04.380
passage i feel like as a python developer producing docs in the like sphinx world you just
00:22:04.520 --> 00:22:10.100
kind of like you learn i learned sphinx and rst to generate docs essentially uh it's like yeah i
00:22:10.160 --> 00:22:16.200
feel like that was my rite of passage into like software development 100 so we've also got mk docs
00:22:16.520 --> 00:22:22.640
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
00:22:22.640 --> 00:22:28.300
you had the zensical people so i feel like they do you have a read on it if i try to remember i
00:22:28.320 --> 00:22:35.560
like martin said mk docs but whoa i i not he could have easily said make docs and i was not paying
00:22:35.740 --> 00:22:41.980
attention yeah um i'm a doctor so yeah no i think that i think that makes sense a lot of these that
00:22:42.220 --> 00:22:46.920
could be said one way or another i really wish and maybe this does but i really wish on their
00:22:47.180 --> 00:22:51.200
github repo they just have a little mp3 like here's how you say it you know what i mean
00:22:51.420 --> 00:22:58.440
little audio button yeah exactly it's like a green unicorn like g unicorn versus goonicorn is
00:22:58.620 --> 00:23:04.300
like a one that i think goes around and around still yeah okay so zensical is um one of the more
00:23:04.450 --> 00:23:10.400
modern ones so i think that that's pretty interesting i don't honestly i'm not sure how
00:23:10.560 --> 00:23:17.340
much it lands in the sphinx mcdocs world or in the other maybe the just pure static site generator
00:23:17.600 --> 00:23:24.200
side of things i mean the sensical folks came on and probably have the best sense but um my sense
00:23:24.260 --> 00:23:28.720
is it's also meant to be kind of a i might be wrong drop-in replacement for make docs i know
00:23:28.730 --> 00:23:34.940
their community yeah yeah it is a it is a um compatibility at least compatible uh for a material
00:23:35.100 --> 00:23:40.320
for make docs yeah right right right yeah for sure so yeah i would say it's in that in that realm
00:23:40.560 --> 00:23:44.620
it also seems like they're heading towards general purpose or knowledge bases which goes
00:23:44.640 --> 00:23:50.300
maybe a bit beyond just like yes exactly that was my like uncertainty is how do i classify it right
00:23:50.300 --> 00:23:56.060
because it's it doesn't even necessarily if you look at their h2 it doesn't say the best way to
00:23:56.060 --> 00:24:02.840
make your docs right it's it's a scalable way for technical writing right which makes it i think
00:24:03.000 --> 00:24:10.020
land a little more in the hugo or ghost side of um thing so that's another part to part to talk
00:24:09.980 --> 00:24:15.000
about it's just like static sites in general you know why would i choose say sphinx over hugo or
00:24:15.140 --> 00:24:19.500
hugo over sphinx or something like that you guys got yeah it seems a bit like mitlefy they have the
00:24:19.500 --> 00:24:24.900
same sort of thing going to they do documentation sites but they go a bit beyond it's like general
00:24:25.060 --> 00:24:30.480
purpose lots of different languages supported uh but it is documentation but not really so much
00:24:30.580 --> 00:24:36.300
like a site like just general purpose site generator so it's so hugo and ghost i don't know
00:24:36.320 --> 00:24:37.040
goes very well,
00:24:37.200 --> 00:24:37.580
but Hugo,
00:24:37.760 --> 00:24:41.680
for example, I use that a lot for blogs. I've seen one of my friends does
00:24:41.840 --> 00:24:46.120
really cool stuff just in general with Hugo making general purpose sites.
00:24:46.620 --> 00:24:47.960
I feel like this is much
00:24:48.120 --> 00:24:48.920
more focused on,
00:24:49.200 --> 00:24:54.040
I just need a static site and much less, I need it to read my doc strings and
00:24:54.420 --> 00:25:00.060
categorize my modules and, and API calls and put in that kind of stuff. Right. So that's another,
00:25:00.620 --> 00:25:04.280
another realm that is similar to what you all are doing, but certainly not the same.
00:25:04.460 --> 00:25:04.640
Yeah,
00:25:04.830 --> 00:25:08.960
if you want to throw another one in, there's Quarto by the company we work at, Posit,
00:25:09.200 --> 00:25:12.960
and that does sites and much more beyond.
00:25:13.420 --> 00:25:19.960
I do think I had JJ on and I'm so sorry, I'm forgetting the name of the other guy.
00:25:19.960 --> 00:25:20.040
Oh,
00:25:20.220 --> 00:25:20.320
Charles.
00:25:20.720 --> 00:25:21.260
Yeah, I think it was Charles.
00:25:21.260 --> 00:25:21.320
Oh,
00:25:21.580 --> 00:25:21.700
cool.
00:25:21.840 --> 00:25:23.840
To talk about Quarto a little while ago.
00:25:23.850 --> 00:25:24.280
That was fun.
00:25:24.640 --> 00:25:24.900
Yeah.
00:25:24.940 --> 00:25:30.800
I do think a lot of the questions with like Hugo versus something more targeted at like docs for a
00:25:30.800 --> 00:25:32.900
tool is hitting on kind of like,
00:25:33.220 --> 00:25:35.240
what are the parts of a doc site?
00:25:35.580 --> 00:25:36.600
You know, like what's technical
00:25:36.880 --> 00:25:38.740
writing versus like package documentation?
00:25:39.620 --> 00:25:42.100
Am I just doing a Hugo thing? Like is what I'm doing
00:25:42.680 --> 00:25:46.060
similar enough to like a blog or a website with content,
00:25:46.580 --> 00:25:48.440
which is really common, like my website's
00:25:48.460 --> 00:25:48.960
in Hugo?
00:25:50.130 --> 00:25:55.560
Or do I need something special to like dump out my like API docs to dump out the things
00:25:55.680 --> 00:25:57.120
from my like functions and classes?
00:25:57.800 --> 00:25:59.780
Or could I jam that into Hugo?
00:26:00.360 --> 00:26:01.660
That's a common kind of hybrid
00:26:01.900 --> 00:26:02.080
path.
00:26:02.440 --> 00:26:05.180
Could my thing just dump my info into Hugo?
00:26:05.760 --> 00:26:07.860
It's all kind of this dance between really,
00:26:08.220 --> 00:26:09.840
is this a general content problem?
00:26:10.400 --> 00:26:13.140
Is this a like very specific tool problem?
00:26:13.590 --> 00:26:14.680
Or can I kind of like
00:26:14.700 --> 00:26:16.860
jam them both together into something.
00:26:17.280 --> 00:26:18.900
Yeah, that's an interesting problem.
00:26:18.980 --> 00:26:22.920
So maybe a good time to start talking about, you know, great docs.
00:26:23.720 --> 00:26:24.120
What is it?
00:26:24.960 --> 00:26:29.500
Like, what's its value prop and positioning with regard to these other areas?
00:26:30.480 --> 00:26:32.120
Well, on your screen, you have package down.
00:26:32.480 --> 00:26:32.740
Yes.
00:26:33.240 --> 00:26:33.860
It has an origin.
00:26:34.020 --> 00:26:34.140
Actually,
00:26:34.560 --> 00:26:35.040
coming from R,
00:26:35.200 --> 00:26:38.900
I can't help but to be a little bit influenced by package down.
00:26:39.100 --> 00:26:41.300
I use it a lot in my R projects.
00:26:42.000 --> 00:26:46.960
And I kind of felt like there was like a package downsized hole in the Python docs ecosystem,
00:26:47.320 --> 00:26:50.960
just a little bit, where, you know, you can just point something at your docs and it makes
00:26:51.060 --> 00:26:53.400
something pretty fast with pretty much no configuration.
00:26:53.940 --> 00:26:54.440
That's like the challenge.
00:26:54.680 --> 00:26:56.560
Does it present something that's serviceable,
00:26:56.840 --> 00:26:57.740
like usable right away?
00:26:58.680 --> 00:26:59.920
And that's what I was shooting for.
00:26:59.920 --> 00:27:01.820
And I think that's kind of like where I landed.
00:27:02.300 --> 00:27:04.700
And of course, we have tons of options to do way more things.
00:27:04.980 --> 00:27:06.400
But I wanted to give something that was,
00:27:06.960 --> 00:27:07.080
you know,
00:27:07.240 --> 00:27:09.640
you just start it right away and it gives
00:27:09.640 --> 00:27:09.920
you something.
00:27:10.520 --> 00:27:11.160
Like, for instance,
00:27:11.500 --> 00:27:12.840
you have doc strings and such,
00:27:13.100 --> 00:27:18.420
and they all just get captured and put into the API reference section.
00:27:18.700 --> 00:27:23.660
And then later on, you would, you know, attend to it and organize it and then, you know, arrange it and exclude things.
00:27:24.420 --> 00:27:26.360
At the very beginning, it would just give you something at least.
00:27:26.680 --> 00:27:28.580
So that was kind of like my goal.
00:27:28.960 --> 00:27:32.340
The up and running super quick is one of the themes,
00:27:32.540 --> 00:27:32.640
right?
00:27:32.900 --> 00:27:33.180
Yeah,
00:27:33.360 --> 00:27:33.500
yeah,
00:27:33.880 --> 00:27:34.200
absolutely.
00:27:34.580 --> 00:27:35.140
Because I think,
00:27:35.330 --> 00:27:35.740
I suspect,
00:27:35.960 --> 00:27:40.880
maybe a lot of people are getting more into Python now because of agents, AI, LLMs,
00:27:41.030 --> 00:27:41.480
and such,
00:27:41.820 --> 00:27:43.140
and are spinning up small projects.
00:27:43.780 --> 00:27:49.680
And maybe they're even building their documentation sites with using the same things, like LLMs.
00:27:50.640 --> 00:27:51.980
So getting something up quickly.
00:27:52.230 --> 00:27:53.680
And maybe the project doesn't last very long.
00:27:54.000 --> 00:27:56.040
It's just like something just to get going.
00:27:56.320 --> 00:27:59.200
And you don't want to spend a ton of time on learning the docs,
00:27:59.480 --> 00:28:00.400
a new doc system.
00:28:00.730 --> 00:28:01.900
So this sort of thing is pretty valuable.
00:28:02.520 --> 00:28:03.620
But we still give you the opportunity,
00:28:03.820 --> 00:28:04.220
of course, to,
00:28:04.480 --> 00:28:06.340
you know, like add things and do really
00:28:06.500 --> 00:28:06.580
cool,
00:28:06.980 --> 00:28:07.640
sophisticated sites.
00:28:07.760 --> 00:28:10.380
But just the up and running part, it was super important to me.
00:28:10.580 --> 00:28:11.460
So by default,
00:28:11.680 --> 00:28:15.040
you can point it at a package or set of Python files or something and say,
00:28:15.460 --> 00:28:16.660
generate docs around that.
00:28:16.800 --> 00:28:21.220
And it will look for doc strings and so on, and then generate some kind of hierarchical.
00:28:21.480 --> 00:28:21.940
Yeah, exactly.
00:28:22.360 --> 00:28:26.020
And we tested it quite a bit on different package layouts,
00:28:26.460 --> 00:28:26.520
like,
00:28:26.720 --> 00:28:27.060
you know, different
00:28:27.420 --> 00:28:27.860
packaging systems.
00:28:28.340 --> 00:28:31.340
And it seems introspect pretty well based on all sorts of variation.
00:28:32.200 --> 00:28:33.560
and we do test this a lot.
00:28:34.020 --> 00:28:37.100
So the promise is that it does give you something.
00:28:37.420 --> 00:28:38.500
And you can also create
00:28:38.900 --> 00:28:41.200
just more static site type stuff as well, yeah?
00:28:41.500 --> 00:28:42.400
Yeah, oh, absolutely,
00:28:42.660 --> 00:28:42.720
yeah,
00:28:42.960 --> 00:28:43.120
you can.
00:28:43.300 --> 00:28:45.240
I think the user guide's a good example.
00:28:45.540 --> 00:28:49.380
Like if you click the expandable thing in the top left.
00:28:49.780 --> 00:28:51.120
Yeah, everything's so zoomed.
00:28:51.340 --> 00:28:52.540
Yeah, everything's so zoomed
00:28:52.550 --> 00:28:54.780
on my little small streaming screen.
00:28:55.020 --> 00:28:55.740
So yeah,
00:28:55.900 --> 00:28:56.700
the user guide got it.
00:28:57.540 --> 00:28:59.180
It's nice, the user guide's just a folder
00:28:59.440 --> 00:29:01.840
in the repo with files in it.
00:29:01.880 --> 00:29:05.480
But it's nice like that that puts up this like,
00:29:05.780 --> 00:29:05.860
yeah,
00:29:06.040 --> 00:29:11.080
more kind of general bit of content where it's not your API reference,
00:29:12.400 --> 00:29:15.320
which is like each individual function explained,
00:29:15.560 --> 00:29:18.380
but a more general kind of guide,
00:29:18.940 --> 00:29:19.600
kind of like a bigger,
00:29:19.980 --> 00:29:20.860
higher level,
00:29:21.400 --> 00:29:22.940
like introduction to the package.
00:29:23.320 --> 00:29:24.840
But it's nice that to your point,
00:29:25.000 --> 00:29:25.120
like,
00:29:25.540 --> 00:29:27.080
can you have more general kind of content?
00:29:27.560 --> 00:29:27.780
It's nice.
00:29:27.880 --> 00:29:29.100
This is just a folder in the repo.
00:29:29.700 --> 00:29:31.380
So getting started with the user guides,
00:29:31.540 --> 00:29:32.400
like super fast.
00:29:32.780 --> 00:29:32.840
Yeah.
00:29:33.120 --> 00:29:34.540
And this site is like a demonstration.
00:29:34.640 --> 00:29:38.900
We're showing like the great docs site and we're just looking at it and you can just
00:29:39.160 --> 00:29:42.700
add another directory and like recipes at the top nav.
00:29:43.040 --> 00:29:43.800
That's just another directory.
00:29:44.000 --> 00:29:46.520
And we sort of declared it in our configuration file.
00:29:46.940 --> 00:29:49.020
So you can just create something similar to a user guide.
00:29:49.360 --> 00:29:53.520
But we sort of treat a user guide as a sort of like a first class thing because we,
00:29:53.960 --> 00:29:56.760
well, I'm a little bit opinionated about how sites,
00:29:57.300 --> 00:29:58.120
these doc sites should be.
00:29:58.420 --> 00:29:59.360
So it kind of serves as a model.
00:29:59.560 --> 00:30:01.640
So like the idea is that if someone sees this and says,
00:30:02.020 --> 00:30:03.280
yeah, I would like something like this,
00:30:03.540 --> 00:30:05.100
then like three docs would be a good fit.
00:30:05.100 --> 00:30:06.720
You just have sort of emulate what we have here,
00:30:07.080 --> 00:30:12.280
do a few things and you've pretty much got it beyond the simple sort of like init and then like build.
00:30:12.600 --> 00:30:13.520
We can just go a little bit beyond.
00:30:14.040 --> 00:30:14.120
Yeah,
00:30:14.280 --> 00:30:17.840
sitting here talking to you makes me think, you know, I've got some open source projects.
00:30:18.040 --> 00:30:19.340
I really should have better docs with him.
00:30:19.680 --> 00:30:19.800
Maybe.
00:30:20.220 --> 00:30:22.660
Maybe I'll try working on them with great docs.
00:30:22.720 --> 00:30:23.380
That would be really fun.
00:30:23.660 --> 00:30:24.140
Oh, yeah.
00:30:24.420 --> 00:30:25.020
And I love your feedback.
00:30:25.180 --> 00:30:26.840
I'm always looking for ideas and feedback.
00:30:27.720 --> 00:30:27.960
Right now,
00:30:28.380 --> 00:30:30.100
I'm not going to make a big deal of it.
00:30:30.180 --> 00:30:32.100
But I'm looking for users because this is a brand new project.
00:30:32.360 --> 00:30:34.920
So feedback is a bit scant at this point.
00:30:35.240 --> 00:30:35.740
So yeah,
00:30:35.920 --> 00:30:36.960
let me know how it goes.
00:30:37.360 --> 00:30:38.100
Yeah, I will definitely.
00:30:38.520 --> 00:30:43.460
One of the things that's nice here that I'm noticing is it's got a lot of elements of the
00:30:43.480 --> 00:30:49.220
display that go beyond just standard markdown that i think are really nice like for example
00:30:49.580 --> 00:30:55.600
you've got these oh because these are probably like little tags or badges yeah yeah and then
00:30:55.700 --> 00:31:02.340
also you've got a tabbed UI for like here's how you install it on mac Linux windows but in the
00:31:02.370 --> 00:31:06.760
same little area right you just like click the tab for your os yeah because tab sets in Quarto
00:31:06.850 --> 00:31:12.140
they're like a Quarto special really they just come part and parcel with Quarto yeah yeah i feel like
00:31:12.060 --> 00:31:14.340
you can do some nice authorship beyond that.
00:31:14.580 --> 00:31:15.920
Like when I was working on my book,
00:31:16.020 --> 00:31:16.240
I'm like,
00:31:16.580 --> 00:31:17.720
I'm going to write it in Markdown,
00:31:17.880 --> 00:31:19.360
but I also want to have these little call outs
00:31:19.520 --> 00:31:20.800
or like an action or,
00:31:21.020 --> 00:31:22.180
you know, the little sidebar,
00:31:22.300 --> 00:31:24.300
like how in the heck am I going to get that
00:31:24.720 --> 00:31:25.920
to come out of Pandoc?
00:31:26.040 --> 00:31:26.520
You know what I mean?
00:31:26.980 --> 00:31:27.140
Yeah.
00:31:27.720 --> 00:31:30.000
I eventually got it to work by basically
00:31:30.580 --> 00:31:31.920
getting a little pre-parser
00:31:32.160 --> 00:31:33.660
that would just turn those into HTML
00:31:34.180 --> 00:31:35.660
and allow the Markdown to have HTML.
00:31:35.920 --> 00:31:37.960
I think that's what makes a good user guide
00:31:38.180 --> 00:31:38.960
a good user guide.
00:31:39.140 --> 00:31:39.920
We actually show,
00:31:40.220 --> 00:31:41.520
like, not just like show the code,
00:31:41.640 --> 00:31:42.480
but actually show the results.
00:31:43.020 --> 00:31:46.500
And you can totally do that with a good user guide.
00:31:46.840 --> 00:31:48.640
And that's what I try to demonstrate here
00:31:48.880 --> 00:31:50.380
in the Great Docs user guide
00:31:50.720 --> 00:31:52.180
that we have these things.
00:31:52.520 --> 00:31:53.140
Here's how they look.
00:31:53.640 --> 00:31:54.420
You can have these too.
00:31:54.620 --> 00:31:56.600
Yeah, that definitely looks good.
00:31:56.800 --> 00:31:58.180
That's the one thing too with Quarto
00:31:58.500 --> 00:32:01.080
that if I had to make the case for Quarto
00:32:01.200 --> 00:32:03.180
for a lot of people doing documentation,
00:32:03.920 --> 00:32:05.900
it's that it's really easy to run code.
00:32:06.100 --> 00:32:08.820
Running code is kind of like most of Quarto's game.
00:32:09.400 --> 00:32:12.000
It's a you author using a QMD.
00:32:12.380 --> 00:32:13.900
It's essentially a markdown file,
00:32:14.500 --> 00:32:17.260
but your code blocks can be executed.
00:32:17.620 --> 00:32:19.140
So it's really inconvenient for docs,
00:32:19.380 --> 00:32:24.640
like being able to include code snippets with their out and then they get run and their outputs are there.
00:32:25.480 --> 00:32:27.100
So that's kind of the impetus,
00:32:27.320 --> 00:32:32.060
I think, in this case for Quarto is doing like really easy execution of code.
00:32:33.040 --> 00:32:34.780
It's possible in other tools.
00:32:35.140 --> 00:32:37.380
And I know mkdocstrings,
00:32:37.890 --> 00:32:41.360
who I think its author is working with Zensical now too.
00:32:41.660 --> 00:32:46.840
But they've created a lot of good ways for you to be able to do this as well, like execute code.
00:32:47.070 --> 00:32:50.780
But I do think that's one area where people stub their toe a lot is like,
00:32:51.060 --> 00:32:51.140
oh,
00:32:51.360 --> 00:32:53.520
like if I'm Polars or Pandas, I'm a data frame library.
00:32:54.060 --> 00:32:55.280
I probably want a lot of examples.
00:32:56.760 --> 00:33:01.180
And then you get stuck in this like funny dance, like how do I execute the code for my examples?
00:33:01.640 --> 00:33:04.940
And so I think tools like Quarto are really kind of aimed at that.
00:33:05.260 --> 00:33:11.400
use case like you're a person running code and generating reports you know that that have code
00:33:11.400 --> 00:33:17.740
and that produce graphs and tables and yeah and i think the examples like being executable made the
00:33:17.940 --> 00:33:22.720
great tables examples really powerful you can see the code for a table and then see the table
00:33:23.220 --> 00:33:27.620
right below like in the actual like site which is we didn't have to paste that in it was basically
00:33:27.630 --> 00:33:31.880
just generated right there yeah that's amazing which is actually incredibly you can put pros
00:33:31.900 --> 00:33:37.520
around it as well so it's like it reads just like a little mini guide in each doc string does it
00:33:38.160 --> 00:33:44.300
run at build time or does it somehow run in the website oh build time yeah yeah yeah you guys
00:33:44.540 --> 00:33:49.280
embedding WebAssembly or something fun like that no you could do that you could do that yeah i
00:33:49.680 --> 00:33:55.960
another nice thing you can freeze it so like if you have a bit of code that um or like let's say
00:33:55.960 --> 00:34:01.860
you have a blog post and you don't want to rerun it every time because like over the years maybe
00:34:01.880 --> 00:34:05.780
you like know the code's going to get out of date or it takes a long time to run.
00:34:06.120 --> 00:34:06.500
You can do
00:34:06.620 --> 00:34:07.320
something called freeze.
00:34:07.900 --> 00:34:08.980
You can Quarto freeze it.
00:34:09.159 --> 00:34:12.139
And that essentially like caches the outputs
00:34:12.919 --> 00:34:18.320
so that you can re-render it without executing the code every time.
00:34:18.560 --> 00:34:19.179
So that's useful.
00:34:19.419 --> 00:34:19.480
Like
00:34:19.760 --> 00:34:24.960
great tables, we have kind of a growing log of blog posts and we don't want to re-execute them
00:34:25.120 --> 00:34:27.960
every time because that starts to get pretty time consuming.
00:34:28.340 --> 00:34:29.940
So we can just freeze their outputs
00:34:30.539 --> 00:34:32.360
and then they generate super fast.
00:34:33.100 --> 00:34:34.320
Another reason you might want to freeze it
00:34:34.860 --> 00:34:37.060
is you're doing accessing live data
00:34:37.179 --> 00:34:38.120
off an API or website
00:34:38.460 --> 00:34:39.740
and you want to talk about the results.
00:34:40.100 --> 00:34:41.040
And if it changes,
00:34:41.320 --> 00:34:42.760
like all of a sudden your pros is like,
00:34:43.100 --> 00:34:43.919
why are you talking about this?
00:34:44.000 --> 00:34:44.580
It doesn't say that.
00:34:44.639 --> 00:34:45.800
Well, it used to when I did it.
00:34:46.080 --> 00:34:48.520
You might imagine like a benchmark section example
00:34:48.659 --> 00:34:49.659
if it runs a long time
00:34:49.860 --> 00:34:50.159
or you just,
00:34:50.540 --> 00:34:50.659
you know,
00:34:50.820 --> 00:34:52.740
accessing some keys on your personal machine.
00:34:53.240 --> 00:34:53.480
Absolutely.
00:34:53.860 --> 00:34:54.580
Freezing is great for that.
00:34:54.760 --> 00:34:56.960
You basically froze stuff on your personal computer
00:34:57.380 --> 00:34:57.960
and you're just like,
00:34:58.120 --> 00:34:58.260
you know,
00:34:58.620 --> 00:34:59.580
sending it off to like CI.
00:34:59.660 --> 00:34:59.700
high.
00:35:00.640 --> 00:35:02.120
And I think there's like a million,
00:35:02.560 --> 00:35:04.320
there's also like a million of these things that you
00:35:04.560 --> 00:35:08.980
encounter when you start generating doc sites or like personal content,
00:35:09.480 --> 00:35:10.060
which is like,
00:35:10.360 --> 00:35:10.420
yeah,
00:35:10.550 --> 00:35:11.760
maybe I don't want to run some stuff.
00:35:12.380 --> 00:35:15.120
Maybe I want to like include a snippet from one thing
00:35:15.370 --> 00:35:15.740
somewhere else,
00:35:16.380 --> 00:35:21.540
or maybe I want to do like all kinds of like output customization.
00:35:22.630 --> 00:35:23.140
I just feel
00:35:23.120 --> 00:35:25.320
like there's a million little boxes to check.
00:35:25.500 --> 00:35:27.720
So that's, that's one.
00:35:28.120 --> 00:35:28.480
I mean,
00:35:28.960 --> 00:35:29.640
one other reason we
00:35:29.740 --> 00:35:32.460
use Quarto is we belong to the company that created Quarto.
00:35:32.880 --> 00:35:34.240
But I think those like little
00:35:34.860 --> 00:35:39.740
pieces of detail for people generating like scientific documents and stuff goes a long way.
00:35:39.980 --> 00:35:44.360
It's pretty wild too, because Quarto has a pretty big extension system as well,
00:35:44.580 --> 00:35:45.280
like pretty active.
00:35:45.700 --> 00:35:46.620
So there's like ways,
00:35:46.820 --> 00:35:48.600
I mean, besides like different output types,
00:35:48.780 --> 00:35:49.660
there's like extensions,
00:35:49.940 --> 00:35:51.440
and different types of extensions too,
00:35:51.670 --> 00:35:52.860
like different classes of extensions.
00:35:53.440 --> 00:35:53.940
So it goes really deep.
00:35:54.370 --> 00:35:54.520
Yeah,
00:35:54.740 --> 00:35:55.500
Quarto is really neat.
00:35:56.740 --> 00:35:59.200
This portion of Talk Python To Me is sponsored by Temporal.
00:35:59.640 --> 00:36:02.920
Ever since I had Mason Egger on the podcast for episode 515,
00:36:03.560 --> 00:36:06.020
I've been fascinated with durable workflows in Python.
00:36:06.620 --> 00:36:08.700
That's why I'm thrilled that Temporal has decided
00:36:08.750 --> 00:36:11.120
to become a podcast sponsor since that episode.
00:36:11.940 --> 00:36:14.220
If you've built background jobs or multi-step workflows,
00:36:14.660 --> 00:36:17.540
you know how messy things get with retries, timeouts,
00:36:17.700 --> 00:36:19.800
partial failures, and keeping state consistent.
00:36:20.160 --> 00:36:22.480
I'm sure many of you have written brutal code to
00:36:22.640 --> 00:36:25.560
keep the workflow moving and to track when you run into problems,
00:36:26.140 --> 00:36:27.040
but it's trickier than that.
00:36:27.200 --> 00:36:31.300
What if you have a long-running workflow and you need to redeploy the app or restart the server
00:36:31.560 --> 00:36:32.140
while it's running?
00:36:32.920 --> 00:36:36.060
This is where Temporal's open source framework is a game changer.
00:36:36.820 --> 00:36:41.240
You write workflows as normal Python code and Temporal ensures that they execute reliably,
00:36:41.860 --> 00:36:42.800
even across crashes,
00:36:43.140 --> 00:36:43.480
restarts,
00:36:43.840 --> 00:36:46.620
or long-running processes while handling retries,
00:36:46.820 --> 00:36:46.960
states,
00:36:47.040 --> 00:36:48.360
and orchestrations for you
00:36:48.460 --> 00:36:49.500
so you don't have to build
00:36:49.540 --> 00:36:50.880
and maintain that logic yourself.
00:36:51.780 --> 00:36:54.460
You may be familiar with writing asynchronous code
00:36:54.960 --> 00:36:56.840
using the async and await keywords in Python.
00:36:57.400 --> 00:36:59.020
Temporal's brilliant programming model
00:36:59.400 --> 00:37:01.520
leverages the exact same programming model
00:37:01.820 --> 00:37:03.020
that you are familiar with,
00:37:03.120 --> 00:37:04.180
but uses it for durability,
00:37:04.640 --> 00:37:05.660
not just concurrency.
00:37:06.480 --> 00:37:08.720
Imagine writing await workflow.sleep,
00:37:09.180 --> 00:37:09.500
time delta,
00:37:10.060 --> 00:37:10.460
30 days.
00:37:10.920 --> 00:37:11.500
Yes, seriously,
00:37:11.960 --> 00:37:12.780
sleep for 30 days.
00:37:13.060 --> 00:37:13.640
Restart the server,
00:37:13.940 --> 00:37:14.920
deploy new versions of the app.
00:37:15.200 --> 00:37:15.580
That's it,
00:37:15.780 --> 00:37:16.920
Temporal takes care of the rest.
00:37:17.440 --> 00:37:21.840
temporal is used by teams at netflix snap and nvidia for critical production systems
00:37:22.600 --> 00:37:27.680
get started with the open source python sdk today learn more at talkpython.fm/temporal
00:37:28.400 --> 00:37:32.600
the link is in your podcast player's show notes thank you to temporal for supporting the show
00:37:33.900 --> 00:37:38.640
and you all keep talking about Quarto because it's the foundation of what's happening with
00:37:38.700 --> 00:37:43.020
great tables right it's been a while since it was um been a while since i had jj and carlos on
00:37:43.020 --> 00:37:49.580
the podcast to talk about Quarto but so maybe just give folks a bit of a refresher of what is cordo
00:37:49.660 --> 00:37:54.660
and then how that relates back to great tables um yeah so Quarto is a like a like open source
00:37:55.300 --> 00:38:00.780
publishing system so you can make things like sites um like documents like books for
00:38:00.960 --> 00:38:05.240
instance uh you can make presentations uh it's probably a few more i'm missing and it's cross
00:38:05.460 --> 00:38:10.140
language as well and it and like you know code cells so it has computational notebooks is what
00:38:10.040 --> 00:38:13.780
they call them because they have cells which are basically computational cells which can accept
00:38:14.260 --> 00:38:18.400
which have different engines so you can like say like run some r code run some python some julia
00:38:19.120 --> 00:38:22.240
uh what have you many other things as well and then you can stitch them you know basically render
00:38:22.260 --> 00:38:26.860
them into into documents using Pandoc for the most part and probably other things too for
00:38:27.180 --> 00:38:31.580
different output types and it just really batteries included has things like you just see in them on
00:38:31.580 --> 00:38:37.300
the site citations cross refs you know it's it's got it all essentially and so how it relates to
00:38:37.520 --> 00:38:40.660
to quartodoc and to GreatDocs.
00:38:41.520 --> 00:38:42.300
We're using quartodoc.
00:38:43.710 --> 00:38:44.280
But not really.
00:38:44.480 --> 00:38:45.740
I think with quartodoc,
00:38:47.070 --> 00:38:48.560
the way I see it is like,
00:38:49.740 --> 00:38:50.540
and correct me if I'm wrong, Michael,
00:38:50.740 --> 00:38:51.220
at quartodoc,
00:38:51.700 --> 00:38:53.480
you're creating a reference API,
00:38:53.870 --> 00:38:55.380
but you're still basically using quartodoc.
00:38:55.560 --> 00:38:56.560
You're within the quartodoc itself.
00:38:56.810 --> 00:38:58.360
You're still creating the Quarto config.
00:38:59.600 --> 00:39:00.540
But with GreatDocs,
00:39:00.570 --> 00:39:02.120
it's kind of like quartodoc is a bit sort of like
00:39:02.120 --> 00:39:03.160
we're using it,
00:39:03.340 --> 00:39:03.480
obviously,
00:39:03.820 --> 00:39:05.480
but you don't have to know a lot about quartodoc.
00:39:05.500 --> 00:39:07.880
you can basically get by with just a few things you see,
00:39:08.300 --> 00:39:09.120
you know,
00:39:09.170 --> 00:39:12.140
in like the user guide and not have to like go deeply into Quarto.
00:39:12.270 --> 00:39:15.500
It sort of like hides it a little bit or doesn't really advertise it as much,
00:39:16.380 --> 00:39:17.500
even though we're using a lot.
00:39:17.680 --> 00:39:18.600
Just for some context.
00:39:19.630 --> 00:39:19.760
Yeah.
00:39:19.900 --> 00:39:22.020
I mentioned before I developed a tool called quartodoc,
00:39:22.220 --> 00:39:25.620
which is another documentation generator for Quarto.
00:39:26.160 --> 00:39:26.900
So just,
00:39:27.060 --> 00:39:29.040
just to clarify like the context.
00:39:29.810 --> 00:39:29.940
Yeah.
00:39:30.020 --> 00:39:32.420
Like quartodoc is a much more kind of like low level,
00:39:33.200 --> 00:39:33.820
no frills.
00:39:33.920 --> 00:39:35.860
So like the IBIS project uses it.
00:39:37.120 --> 00:39:38.460
So that's another pretty,
00:39:38.760 --> 00:39:39.660
pretty big Python tool,
00:39:40.000 --> 00:39:42.440
but it's like very like simple.
00:39:42.980 --> 00:39:46.520
It's more about like dump your API reference and then you're responsible
00:39:46.720 --> 00:39:48.000
for like customizing your website.
00:39:48.400 --> 00:39:51.660
And so it's for people who really want to like be in control and set it all up.
00:39:51.850 --> 00:39:54.180
I think Rich is kind of underselling.
00:39:54.210 --> 00:39:56.560
I think great docs is just dripping in style.
00:39:56.630 --> 00:39:57.440
I think that's the,
00:39:57.650 --> 00:40:00.920
one of the keys is it's made to be kind of like an all in one,
00:40:01.080 --> 00:40:04.240
something really nice out of the box that's opinionated.
00:40:04.670 --> 00:40:06.340
But I just want to clarify for context,
00:40:06.560 --> 00:40:08.940
QuartoDoc is another tool outside of Quarto.
00:40:09.420 --> 00:40:11.480
So I know we've checked a lot of tools out.
00:40:12.780 --> 00:40:15.060
But one thing that's interesting is I know,
00:40:15.480 --> 00:40:17.280
like when we look at great docs,
00:40:17.880 --> 00:40:20.260
it's easy to see like some of the stuff that jumps out.
00:40:20.640 --> 00:40:21.240
But there's actually,
00:40:21.940 --> 00:40:22.960
I think to Rich's credit,
00:40:23.080 --> 00:40:25.660
there's a ton of like little things inside great docs
00:40:25.750 --> 00:40:28.660
that you almost don't notice until you need them.
00:40:29.940 --> 00:40:32.500
Like there's a million little pieces to doc sites.
00:40:32.920 --> 00:40:34.480
And some of them are actually pretty intriguing.
00:40:34.800 --> 00:40:37.860
Like if you go to the great docs API reference,
00:40:38.460 --> 00:40:46.240
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,
00:40:46.720 --> 00:40:48.740
including this little like filter bar.
00:40:49.000 --> 00:40:50.860
So if you click on the top left,
00:40:51.220 --> 00:40:51.700
there's a,
00:40:52.200 --> 00:40:55.140
you can sort of like filter on the page for different pieces.
00:40:55.980 --> 00:40:56.620
That's like,
00:40:57.760 --> 00:40:57.820
yeah.
00:40:58.300 --> 00:41:00.440
I think for just to illustrate the difference.
00:41:00.580 --> 00:41:02.360
So quartodoc is a really bare bones tool.
00:41:02.620 --> 00:41:04.680
It's like we generate an API for you.
00:41:05.220 --> 00:41:10.080
Great docs like this thing, this filter bar where you can like type in it and it shows you live on the page.
00:41:10.520 --> 00:41:12.840
Like it filters your reference items.
00:41:13.500 --> 00:41:14.420
That's just pure rich,
00:41:14.900 --> 00:41:18.020
just like wilding out on what docs could be.
00:41:18.340 --> 00:41:23.300
And I think there are like a million little examples of this kind of in great docs.
00:41:23.860 --> 00:41:24.240
Kind of. Yeah.
00:41:24.440 --> 00:41:26.980
Cause like I find little things that annoy me and I want to fix them.
00:41:27.360 --> 00:41:27.500
But,
00:41:27.840 --> 00:41:28.100
um,
00:41:28.370 --> 00:41:28.480
uh,
00:41:28.800 --> 00:41:29.660
and so this is my,
00:41:30.560 --> 00:41:31.220
this is almost like a,
00:41:31.460 --> 00:41:33.540
like a, like a Python site generator
00:41:34.000 --> 00:41:34.240
for,
00:41:34.440 --> 00:41:38.200
for me in lots of ways, but I'm hoping that other people feel these little pain points
00:41:38.250 --> 00:41:38.560
as well.
00:41:38.880 --> 00:41:40.380
I've certainly felt I've gone to,
00:41:40.650 --> 00:41:40.740
um,
00:41:41.120 --> 00:41:43.420
documentation sites and search for stuff on there.
00:41:43.720 --> 00:41:45.340
And then you see a little spinner searching,
00:41:45.840 --> 00:41:47.260
searching static site.
00:41:47.270 --> 00:41:47.740
What are we doing?
00:41:48.000 --> 00:41:48.720
Why am I waiting?
00:41:49.140 --> 00:41:50.600
This doesn't make any sense to me, but okay.
00:41:51.020 --> 00:41:51.180
Yeah.
00:41:51.480 --> 00:41:51.540
Yeah.
00:41:51.940 --> 00:41:53.280
Even the CLI button,
00:41:53.730 --> 00:41:53.860
like,
00:41:54.630 --> 00:41:56.120
oh, sorry, if you click that,
00:41:56.520 --> 00:41:59.000
that's like if you have a command line interface for your tool,
00:41:59.270 --> 00:42:00.740
which is so hot today,
00:42:01.000 --> 00:42:03.440
like AI loves command line interfaces.
00:42:04.680 --> 00:42:07.380
Claude Codes just bash executing everything.
00:42:08.020 --> 00:42:09.880
You know, a lot of people have CLIs.
00:42:11.240 --> 00:42:17.500
I think it also speaks a lot to Richestile that he created this spot for your CLI docs to live.
00:42:18.520 --> 00:42:18.980
Very important.
00:42:20.160 --> 00:42:21.480
And then at the top right,
00:42:21.780 --> 00:42:22.240
if you look,
00:42:23.380 --> 00:42:24.180
there's like a copy.
00:42:24.260 --> 00:42:28.000
You can copy the whole page to Markdown or view it as Markdown.
00:42:28.460 --> 00:42:30.220
I never would have thought of that.
00:42:30.420 --> 00:42:31.040
To me,
00:42:31.240 --> 00:42:33.980
I would never go that far to give people something nice.
00:42:34.340 --> 00:42:37.220
I don't know if I'm just like a curmudgeony engineer.
00:42:37.660 --> 00:42:39.460
I think Rich is just dreaming up,
00:42:39.680 --> 00:42:42.880
I don't know, different ways you could interact with docs,
00:42:43.100 --> 00:42:44.300
copy the page to Markdown.
00:42:44.560 --> 00:42:46.660
And I don't doubt that it's incredibly useful.
00:42:47.320 --> 00:42:48.100
To me, this strikes me as like...
00:42:48.100 --> 00:42:49.100
I think it's very useful, yeah.
00:42:49.420 --> 00:42:49.580
Yeah.
00:42:50.440 --> 00:42:52.740
When I saw that table graph for great tables,
00:42:53.080 --> 00:42:55.520
like breaking apart the table into every little piece,
00:42:56.040 --> 00:42:57.320
this strikes me as rich again,
00:42:57.780 --> 00:43:01.360
like imagining every little thing a doc site could do.
00:43:01.840 --> 00:43:05.460
So I think that's why I'm so kind of gassed up about great docs.
00:43:05.720 --> 00:43:06.320
This is delightful.
00:43:06.720 --> 00:43:10.940
And we're going to come back to AI stuff later, but we don't have that much time left,
00:43:11.200 --> 00:43:11.380
honestly,
00:43:11.560 --> 00:43:11.700
guys.
00:43:11.820 --> 00:43:15.460
We've been talking and not making a lot of progress because it's really, we're just diving into it.
00:43:15.480 --> 00:43:15.680
Docs talk.
00:43:15.680 --> 00:43:16.180
It's so fun.
00:43:16.340 --> 00:43:16.880
I know.
00:43:16.980 --> 00:43:17.500
It's so fun.
00:43:17.960 --> 00:43:24.500
But I can easily see I'm working on a project and I've got Claude or some codex or whatever,
00:43:24.780 --> 00:43:27.420
and it's just not getting it for a certain function.
00:43:27.820 --> 00:43:29.460
Just go over to the docs, hit copy pages,
00:43:29.640 --> 00:43:31.500
markdown, and just go, no AI,
00:43:31.880 --> 00:43:33.500
this is the docs, read it.
00:43:33.940 --> 00:43:39.380
Because giving it a markdown result of what this is versus all the nav and all the stuff,
00:43:39.390 --> 00:43:44.240
and it's trying to understand what's the essence of the page, if you tell it to just go to the page,
00:43:44.520 --> 00:43:45.400
really, really different.
00:43:45.720 --> 00:43:46.620
Yeah, it's been more immediate,
00:43:46.880 --> 00:43:47.120
I think.
00:43:47.460 --> 00:43:51.480
Also, you can change the URL if you really want to, to.md and just give it the URL.
00:43:51.850 --> 00:43:53.040
So many ways to do it.
00:43:53.560 --> 00:43:53.720
Yeah,
00:43:53.940 --> 00:43:54.340
yeah, yeah.
00:43:54.410 --> 00:43:54.960
I love that.
00:43:55.260 --> 00:43:56.520
So it said html.md.
00:43:56.900 --> 00:43:57.180
Yeah.
00:43:57.480 --> 00:43:57.660
Yeah.
00:43:58.120 --> 00:43:58.860
That's really cool.
00:43:59.180 --> 00:44:01.840
So if you were plot code or reading the docs,
00:44:02.080 --> 00:44:03.580
you know, a lot of good stuff.
00:44:03.580 --> 00:44:03.620
Yeah,
00:44:03.780 --> 00:44:04.280
season tokens.
00:44:04.880 --> 00:44:05.040
Yeah,
00:44:05.220 --> 00:44:05.520
yeah, yeah.
00:44:05.640 --> 00:44:05.920
That's cool.
00:44:06.240 --> 00:44:07.280
Did I do that for Talk Python?
00:44:07.380 --> 00:44:08.180
I think I did.
00:44:08.600 --> 00:44:08.660
Yeah.
00:44:08.960 --> 00:44:10.300
You do that on Talk Python, by the way.
00:44:10.950 --> 00:44:14.720
You can just put.md on the end of any episode name,
00:44:15.030 --> 00:44:17.420
and it gives you the markdown equivalent
00:44:17.640 --> 00:44:21.560
that as well so which is all the rage yeah so i mean we're on the same vibes here i'm loving it
00:44:21.660 --> 00:44:26.840
you know what i mean and it might even help for context i'd be curious to hear your like when you
00:44:27.020 --> 00:44:32.680
added that markdown and some of your motivation for markdownifying your site i didn't do it for
00:44:32.800 --> 00:44:40.180
people i did it for ai and seo the machine stuff yeah for the machine so um i i added a i did an
00:44:40.340 --> 00:44:47.400
llms.txt to try to get the ais to understand the podcast better and some of the things that i gave
00:44:47.420 --> 00:44:50.200
was this ability to just put Markdown at the end,
00:44:50.220 --> 00:44:52.900
but also I added like a CLI and an MCP
00:44:53.200 --> 00:44:55.920
and different things for an API,
00:44:56.280 --> 00:44:56.740
search API.
00:44:56.940 --> 00:44:57.800
I'm like, okay, AI,
00:44:58.200 --> 00:45:01.200
there's 7.5 million words of content over 11 years.
00:45:01.380 --> 00:45:03.360
I want you to know about it and be able to use it.
00:45:03.960 --> 00:45:07.060
How many ways can I imagine giving something to it?
00:45:07.200 --> 00:45:09.680
And this render as Markdown was certainly one of them.
00:45:09.920 --> 00:45:12.220
I also added some silly stuff that's like for,
00:45:13.500 --> 00:45:13.900
just for me,
00:45:14.260 --> 00:45:15.480
because I've got, for example,
00:45:15.640 --> 00:45:16.900
I've got to update,
00:45:17.220 --> 00:45:17.360
say,
00:45:17.520 --> 00:45:19.340
the YouTube recommendations.
00:45:20.319 --> 00:45:22.460
So, or listings after the live stream,
00:45:22.530 --> 00:45:23.780
I want them to have like links and stuff.
00:45:23.790 --> 00:45:25.880
So I can say dot YouTube on the end
00:45:26.180 --> 00:45:29.080
and it gives me the contents for like the YouTube render.
00:45:29.460 --> 00:45:31.080
So it kind of was building on this,
00:45:31.240 --> 00:45:33.940
like how can I help myself be more efficient,
00:45:34.070 --> 00:45:34.780
but also machines?
00:45:35.020 --> 00:45:36.460
So anyway, that's the story.
00:45:36.680 --> 00:45:36.980
This is great.
00:45:36.990 --> 00:45:38.500
It's like Doc's workflow really,
00:45:38.680 --> 00:45:38.760
right?
00:45:38.980 --> 00:45:39.840
It fits in nicely.
00:45:40.220 --> 00:45:41.060
You know, circling back around,
00:45:41.120 --> 00:45:43.320
I'm really impressed with some of these little nuances
00:45:43.580 --> 00:45:44.460
that are super nice.
00:45:45.220 --> 00:45:45.620
I think that's great.
00:45:46.120 --> 00:45:46.660
Great talks.
00:45:46.830 --> 00:45:47.680
If you want to go further on this,
00:45:48.299 --> 00:45:49.900
it's basically just nicing up the docs
00:45:50.120 --> 00:45:51.100
and make them good for humans,
00:45:51.350 --> 00:45:55.480
but also consumable by LLMs or agents and such.
00:45:55.760 --> 00:45:56.460
Rich, it's a fad.
00:45:56.740 --> 00:45:57.760
We don't really need to worry about it.
00:45:58.220 --> 00:45:58.880
It's going to go away.
00:45:59.000 --> 00:45:59.360
It'll pass,
00:45:59.590 --> 00:45:59.680
yeah.
00:45:59.800 --> 00:46:00.660
The bubble's going to burst.
00:46:00.710 --> 00:46:02.280
We can just ignore it.
00:46:02.340 --> 00:46:03.100
It's going to be fine.
00:46:03.840 --> 00:46:03.940
No.
00:46:04.680 --> 00:46:05.340
So let's talk.
00:46:06.120 --> 00:46:07.620
I want to talk about a couple of things here.
00:46:07.670 --> 00:46:10.120
So let's just do like a real quick little walkthrough
00:46:10.360 --> 00:46:12.100
of maybe getting started with this.
00:46:13.660 --> 00:46:16.440
It's honestly not a whole lot to get started, but give us this.
00:46:17.020 --> 00:46:20.680
One of you all walk us through the quick start just so people know what's involved.
00:46:21.020 --> 00:46:21.220
Yeah.
00:46:21.480 --> 00:46:22.760
So really that command,
00:46:23.140 --> 00:46:23.740
like great docs init,
00:46:24.160 --> 00:46:25.900
that'll make the file that is basically what
00:46:25.920 --> 00:46:26.780
you need for the build.
00:46:27.100 --> 00:46:29.240
And with a lot of testing,
00:46:29.420 --> 00:46:32.580
it should work on many different Python package layouts and
00:46:32.740 --> 00:46:32.880
types.
00:46:33.360 --> 00:46:34.220
So you just need that.
00:46:34.400 --> 00:46:35.900
Of course, yeah, install great docs,
00:46:36.320 --> 00:46:37.620
install Quarto as well.
00:46:37.780 --> 00:46:39.720
So we got that as well before that.
00:46:40.020 --> 00:46:43.000
But once you have those things, it should do what it says on the screen, basically show
00:46:43.020 --> 00:46:43.740
you stuff in the terminal,
00:46:44.380 --> 00:46:45.180
which is all positive.
00:46:45.360 --> 00:46:48.160
It's creating that great docs.yaml file.
00:46:48.580 --> 00:46:49.960
And it should be pretty minimal what's in there.
00:46:50.680 --> 00:46:52.220
It should actually also be a little bit dynamic.
00:46:52.880 --> 00:46:53.640
Based on your project,
00:46:53.880 --> 00:46:59.060
it'll craft the correct great docs.yaml file or the config file.
00:46:59.400 --> 00:47:00.680
And then you could go ahead and customize,
00:47:00.920 --> 00:47:02.680
but you might just jump to building your documentation
00:47:03.480 --> 00:47:04.860
because that's the next easiest thing.
00:47:05.080 --> 00:47:07.060
It's just another command, great docs build.
00:47:07.500 --> 00:47:12.240
and what you get is a great hyphen docs directory
00:47:12.740 --> 00:47:13.620
in your working directory.
00:47:14.000 --> 00:47:15.520
And that contains like the site folder.
00:47:15.980 --> 00:47:17.420
But you don't really have to worry about that
00:47:17.420 --> 00:47:19.440
because you have another command called great docs preview,
00:47:19.900 --> 00:47:22.840
which will basically launch like a web server
00:47:23.360 --> 00:47:26.840
and then put the site in your default browser,
00:47:27.100 --> 00:47:29.440
basically just like let you see the site locally.
00:47:29.820 --> 00:47:32.260
And then because I'm a big fan of like people know what's going on,
00:47:32.440 --> 00:47:33.720
so it should be totally a black box.
00:47:34.100 --> 00:47:35.980
I give on this page, like a structure,
00:47:36.320 --> 00:47:38.620
the basic structure of like how it should look
00:47:39.270 --> 00:47:39.920
in your working directory.
00:47:40.720 --> 00:47:41.560
But that's kind of it.
00:47:41.560 --> 00:47:43.100
And I believe the next step for most people
00:47:43.320 --> 00:47:45.140
will just be getting this on CI if they're satisfied
00:47:45.560 --> 00:47:46.780
and then just working from there,
00:47:46.950 --> 00:47:48.840
like modifying their initialization,
00:47:49.340 --> 00:47:49.900
not initialization,
00:47:50.550 --> 00:47:51.640
their config file
00:47:52.170 --> 00:47:54.780
to give the site more customization personality
00:47:55.060 --> 00:47:57.240
and there'll be authoring guides and things like that.
00:47:57.400 --> 00:47:59.800
You've got the really nice watch feature.
00:48:00.110 --> 00:48:01.780
So great docs build --watch.
00:48:02.120 --> 00:48:02.220
Yes.
00:48:02.500 --> 00:48:04.340
Which feels very Hugo to me.
00:48:04.620 --> 00:48:07.780
Like you're going to build it so you can look at it, but then you want to edit it.
00:48:07.830 --> 00:48:08.260
So just,
00:48:08.640 --> 00:48:09.400
if you see any changes,
00:48:09.660 --> 00:48:10.180
just rebuild,
00:48:10.340 --> 00:48:10.440
right?
00:48:10.700 --> 00:48:11.220
Yeah, exactly.
00:48:11.770 --> 00:48:13.880
Small sites will build fast, but this is way faster,
00:48:14.030 --> 00:48:14.140
obviously.
00:48:14.600 --> 00:48:15.560
So yeah,
00:48:15.840 --> 00:48:17.140
this is pretty essential for iterating,
00:48:17.360 --> 00:48:17.860
especially initially.
00:48:18.360 --> 00:48:18.660
Yeah.
00:48:18.660 --> 00:48:18.720
Yeah.
00:48:18.910 --> 00:48:19.980
And what about this version?
00:48:20.090 --> 00:48:22.360
So this is an interesting aspect of the project.
00:48:22.840 --> 00:48:23.180
Versions.
00:48:23.820 --> 00:48:24.260
Well,
00:48:25.880 --> 00:48:27.260
essentially you may have,
00:48:27.480 --> 00:48:27.620
you know,
00:48:27.780 --> 00:48:29.460
multiple tagged versions of your site.
00:48:29.640 --> 00:48:31.680
And this, this is kind of like a wild thing.
00:48:31.740 --> 00:48:35.880
You can have different documentation sites based on your version because you have,
00:48:36.090 --> 00:48:36.380
for instance,
00:48:36.930 --> 00:48:37.720
new things in your API.
00:48:38.110 --> 00:48:41.680
Right. People maybe know that from Python where you can go up here and drop down.
00:48:41.900 --> 00:48:42.800
Exactly. Like version selectors.
00:48:42.960 --> 00:48:45.980
So this is kind of like just seeing like certain versions of your site and it gives you a selector.
00:48:46.360 --> 00:48:47.440
On the GreatDocs site itself,
00:48:47.730 --> 00:48:49.780
we have a selector which is maximal.
00:48:49.950 --> 00:48:51.820
It has like every single version from the very first.
00:48:52.150 --> 00:48:56.540
And you can cruise in there and you'll see that there'll be way less in the earliest versions.
00:48:56.780 --> 00:48:57.120
Like the,
00:48:57.620 --> 00:48:59.740
if you look at the user guide for 0.1,
00:49:00.060 --> 00:49:01.020
which gives a little icon,
00:49:01.420 --> 00:49:02.520
a little scary saying it's unsupported.
00:49:02.860 --> 00:49:04.540
If you look at the user guide, it's pretty sparse.
00:49:04.670 --> 00:49:07.000
Like it's, you know, it's not as long as the other one.
00:49:07.180 --> 00:49:08.820
And if you look at the reference as well,
00:49:09.240 --> 00:49:10.780
it'll have less items.
00:49:11.580 --> 00:49:14.540
So it's aware of like what's available in which versions.
00:49:15.420 --> 00:49:18.280
And so you sort of set that up yourself or you can just do it through that command.
00:49:19.300 --> 00:49:21.120
Is that based on get tags or what is that?
00:49:21.460 --> 00:49:22.220
Based on get tags.
00:49:22.380 --> 00:49:22.760
Yeah, that's right.
00:49:22.920 --> 00:49:23.020
Okay.
00:49:23.320 --> 00:49:24.640
I was wondering how does it even know?
00:49:24.900 --> 00:49:26.260
Yeah, you have to give it some information.
00:49:26.420 --> 00:49:26.800
Like you have to,
00:49:27.020 --> 00:49:30.080
of course, get the tags, but if you actually configure it to do what's doing here,
00:49:30.380 --> 00:49:30.960
like make the site,
00:49:31.400 --> 00:49:33.480
you just change your configuration to have,
00:49:33.640 --> 00:49:37.180
it's basically just like a small config that you have to do.
00:49:37.540 --> 00:49:39.500
And you can set labels and things like that.
00:49:39.660 --> 00:49:42.700
Can I wildcard it or have it somehow pick up all the versions?
00:49:43.080 --> 00:49:46.880
I mean, you don't want to pick up all tags, but it'd be like star dot star.
00:49:47.320 --> 00:49:49.120
I don't think we have version expressions like that yet.
00:49:49.440 --> 00:49:49.520
Yeah.
00:49:49.820 --> 00:49:50.460
Not yet.
00:49:50.660 --> 00:49:50.760
Okay.
00:49:51.160 --> 00:49:51.800
You know, throw it in there.
00:49:52.460 --> 00:49:56.300
I'm just thinking if I have a project with 27 versions over time.
00:49:56.740 --> 00:49:58.480
Yeah, you probably wouldn't do it through like this interface,
00:49:58.670 --> 00:49:59.400
like Great Docs build.
00:49:59.640 --> 00:50:01.720
This is just for like a pretty quick comparison.
00:50:02.380 --> 00:50:06.720
But if you would do it, like you probably put that in the config file and you'd have to
00:50:07.000 --> 00:50:07.740
manually edit those.
00:50:07.910 --> 00:50:10.660
But I think with a slot or something like that would be better.
00:50:10.980 --> 00:50:11.600
And there's an API,
00:50:11.800 --> 00:50:13.240
of course, if you want to just have a little control.
00:50:13.240 --> 00:50:13.460
Yeah,
00:50:13.620 --> 00:50:14.540
it's kind of, you wouldn't do this,
00:50:14.780 --> 00:50:15.380
but it's just,
00:50:15.560 --> 00:50:16.440
I threw it in there.
00:50:16.880 --> 00:50:17.000
Well,
00:50:17.200 --> 00:50:19.220
probably because your commands use that,
00:50:19.380 --> 00:50:19.480
right?
00:50:19.820 --> 00:50:20.240
Yeah, exactly.
00:50:20.650 --> 00:50:22.080
Might as well just let people know that.
00:50:22.080 --> 00:50:22.140
Just being transparent.
00:50:22.320 --> 00:50:24.720
I suppose. Yeah. Where do we want to go next? Let's,
00:50:24.960 --> 00:50:25.760
let's cover just a couple,
00:50:26.180 --> 00:50:28.500
couple of remaining things here while we're,
00:50:28.860 --> 00:50:31.000
we got time to have, what about open source
00:50:31.320 --> 00:50:31.640
sustainability?
00:50:32.440 --> 00:50:35.840
Like I know you all at Posit are doing a lot of things to open source
00:50:36.580 --> 00:50:37.740
your work and so on.
00:50:37.960 --> 00:50:38.100
Yeah.
00:50:38.400 --> 00:50:41.000
Well, we're pretty much like full-time doing open source work.
00:50:41.780 --> 00:50:42.660
So essentially,
00:50:43.220 --> 00:50:47.560
and so I think these projects have like long life cycles with the same maintainer
00:50:47.680 --> 00:50:48.540
for long periods of time,
00:50:48.880 --> 00:50:51.960
which is great for project stability and things like that. And like,
00:50:52.000 --> 00:50:52.260
you know,
00:50:52.500 --> 00:50:55.740
we're accountable for like, you know, issues that come in and for, you know, releases
00:50:56.160 --> 00:50:57.040
and making sure,
00:50:57.400 --> 00:50:59.200
you know, it's not,
00:50:59.420 --> 00:51:00.340
you know, like dead projects,
00:51:00.560 --> 00:51:01.260
you know, like all the way
00:51:01.380 --> 00:51:01.800
down or whatever.
00:51:02.460 --> 00:51:03.200
So I think,
00:51:03.520 --> 00:51:04.560
I think that's a great thing.
00:51:04.940 --> 00:51:05.520
And for instance,
00:51:05.680 --> 00:51:06.100
like great tables,
00:51:06.660 --> 00:51:07.380
I've been at this since the beginning,
00:51:07.700 --> 00:51:07.880
GT,
00:51:08.080 --> 00:51:09.500
which is where it came from since 2017.
00:51:10.640 --> 00:51:11.380
So I think that
00:51:11.720 --> 00:51:15.060
helps a lot. Adds a lot of credibility to these projects that are not just being abandoned.
00:51:15.220 --> 00:51:15.280
There's
00:51:15.280 --> 00:51:17.860
no fear of it being abandoned or things like that.
00:51:18.020 --> 00:51:18.200
There's,
00:51:18.440 --> 00:51:19.560
there's a person there at least.
00:51:20.000 --> 00:51:23.800
Yeah, and I think Posit's found an interesting business model
00:51:23.960 --> 00:51:26.200
that's been long-term sustaining,
00:51:26.560 --> 00:51:28.000
but still allows you, as you said,
00:51:28.120 --> 00:51:29.480
to sort of work in open source.
00:51:30.300 --> 00:51:31.120
Michael, we're joking.
00:51:31.520 --> 00:51:31.580
Yeah,
00:51:31.920 --> 00:51:33.060
it's really interesting.
00:51:33.300 --> 00:51:36.900
And it's almost like not diving crazy deep
00:51:37.240 --> 00:51:37.860
and doing a podcast.
00:51:38.180 --> 00:51:39.900
My favorite thing to say to people is that
00:51:40.200 --> 00:51:42.540
we have a really large open source engineering team,
00:51:42.840 --> 00:51:43.980
dozens of open source engineers.
00:51:44.480 --> 00:51:47.060
People often ask, how does Posit pay the bills
00:51:47.580 --> 00:51:49.040
for people to work on open source?
00:51:49.520 --> 00:51:51.240
And my favorite thing to say is like,
00:51:51.520 --> 00:51:55.740
we have a bunch of boring enterprise tools and I'm
00:51:56.690 --> 00:51:57.480
no shade on pause.
00:51:57.480 --> 00:51:59.480
I actually think that this is the best case scenario.
00:52:00.100 --> 00:52:04.500
Like we have a lot of tools that solve really painful problems.
00:52:04.800 --> 00:52:05.340
If you're an enterprise,
00:52:06.340 --> 00:52:07.560
they could be useful in other settings,
00:52:07.800 --> 00:52:08.340
but it's like,
00:52:08.620 --> 00:52:08.840
how do I
00:52:08.930 --> 00:52:10.060
run a report every day?
00:52:11.400 --> 00:52:17.880
Or how do I host like Jupyter notebooks or VS Code for my say like data team or our studio?
00:52:18.400 --> 00:52:19.700
Those essentially pay the bills.
00:52:20.200 --> 00:52:22.000
That's Posit Connect and Posit Teams.
00:52:22.240 --> 00:52:24.220
You've got a team of data scientists,
00:52:24.500 --> 00:52:26.420
but you don't necessarily have a DevOps team,
00:52:26.560 --> 00:52:28.840
but you still want to have their stuff running reliably,
00:52:29.080 --> 00:52:29.160
right?
00:52:29.460 --> 00:52:29.620
Yeah,
00:52:30.060 --> 00:52:31.320
and it's a hard problem.
00:52:31.340 --> 00:52:32.020
If you're a company,
00:52:32.400 --> 00:52:33.880
right, these are kind of tricky problems.
00:52:33.940 --> 00:52:36.680
Or you have like a really mean IT team.
00:52:37.500 --> 00:52:41.000
A cruel IT team could hamstring you for years.
00:52:41.480 --> 00:52:44.720
But that's just to say we get to work on open source
00:52:44.900 --> 00:52:46.540
because these tools exist.
00:52:46.980 --> 00:52:48.260
And I think Posit exists,
00:52:48.440 --> 00:52:51.900
I think, because the maintainers care so much about open source.
00:52:53.160 --> 00:52:54.800
I will say in terms of sustainability,
00:52:55.640 --> 00:53:00.480
one interaction I've really liked over the years is like in the docs realm,
00:53:02.100 --> 00:53:02.580
there's this person.
00:53:02.700 --> 00:53:04.300
I only know him as pawamoy,
00:53:05.120 --> 00:53:05.880
his GitHub handle.
00:53:06.140 --> 00:53:09.940
I think it's Maté or Timothy in France,
00:53:10.340 --> 00:53:11.520
I think.
00:53:11.820 --> 00:53:16.920
But he maintains the tools upstream of tools like quartodoc and GreatDocs.
00:53:17.200 --> 00:53:21.420
And we've interacted a bit in the past where I've done PRs on his tools.
00:53:22.400 --> 00:53:23.000
One's called Griffee.
00:53:24.140 --> 00:53:26.820
And I think that's such an important part of sustainability too,
00:53:27.100 --> 00:53:29.980
is that he works on a documentation tool,
00:53:30.380 --> 00:53:31.040
mkdocstrings.
00:53:31.520 --> 00:53:34.440
But we're all able to collaborate on his tool, Griff,
00:53:34.940 --> 00:53:37.160
that actually powers all of our documentation sites.
00:53:37.540 --> 00:53:40.060
So I think that's a really important piece.
00:53:40.120 --> 00:53:42.600
I think to your point about being at PyCon and seeing people,
00:53:43.040 --> 00:53:44.300
I think us as open source
00:53:44.560 --> 00:53:50.640
maintainers chatting and even contributing and working on say like upstream tools is
00:53:50.640 --> 00:53:54.080
a really important part of keeping the ecosystem healthy and sustainable.
00:53:54.260 --> 00:53:58.320
We're not like multiple doc tools competing to a degree.
00:53:58.700 --> 00:54:00.040
I do think they compete,
00:54:00.380 --> 00:54:02.920
but ultimately like we're working on open source because we're
00:54:03.040 --> 00:54:03.320
passionate.
00:54:03.640 --> 00:54:07.460
And I think it helps to collaborate on our kind of like shared tools.
00:54:07.820 --> 00:54:08.500
A hundred percent agree.
00:54:08.740 --> 00:54:09.000
Very cool.
00:54:09.160 --> 00:54:09.380
Now,
00:54:09.940 --> 00:54:12.280
Rich, you mentioned that pretty new project.
00:54:12.760 --> 00:54:12.940
Yeah.
00:54:13.220 --> 00:54:13.720
Where are we going?
00:54:14.120 --> 00:54:15.240
What's on the roadmap?
00:54:15.600 --> 00:54:16.260
Yeah, lots of things.
00:54:16.660 --> 00:54:19.260
I even have a roadmap on the site if anyone's interested.
00:54:20.140 --> 00:54:24.740
But I think it'll be like a lot more like documentation for different things, like new things.
00:54:25.140 --> 00:54:26.120
Like the other day,
00:54:26.380 --> 00:54:29.560
I was suggested to create documentation for MCP servers.
00:54:29.980 --> 00:54:30.320
I was like,
00:54:30.500 --> 00:54:30.900
good idea.
00:54:31.240 --> 00:54:32.080
We don't really have that.
00:54:32.280 --> 00:54:35.420
And it's pretty easy to document JSON,
00:54:35.840 --> 00:54:36.080
essentially.
00:54:36.340 --> 00:54:36.980
So we can take that apart,
00:54:37.140 --> 00:54:38.600
parse that, and present something.
00:54:38.940 --> 00:54:44.280
that's a good point because if you look at the mcp servers they don't have structure in the way that
00:54:44.580 --> 00:54:49.160
traditional projects do right they don't just have like a separate function for each thing they've got
00:54:49.240 --> 00:54:54.500
this kind of weird invocation entry point where you pass like the tool you want to use and yeah it's
00:54:56.120 --> 00:55:00.320
documentation suggestions things like that uh so i think we could do a pretty good job there that's
00:55:00.480 --> 00:55:06.119
the idea is pretty new but like i guess we're yeah just trying to be where or go where things are
00:55:06.080 --> 00:55:12.180
going and be a little bit ahead so would that somehow show itself as like where you've got the
00:55:12.210 --> 00:55:15.920
um the api and the cli would there also be an mcp or what do you think it's gonna be a bit crowded
00:55:16.030 --> 00:55:20.860
so i'm rethinking i know yeah yeah i was like i don't really know this would be it like but no
00:55:20.960 --> 00:55:26.120
that's not quite it there's you know maybe one or two more things uh so it might be just a drop down
00:55:26.300 --> 00:55:32.500
nav on the top like a drop down on the top nav so that's part of the part of like uh what i
00:55:32.420 --> 00:55:32.900
have to think about.
00:55:33.420 --> 00:55:36.220
But there's things like that. And also like a recent thing we just did,
00:55:36.740 --> 00:55:39.900
and this is very new, so it's almost like it's new enough,
00:55:40.060 --> 00:55:40.820
is like skills,
00:55:41.180 --> 00:55:41.900
like publishing skills
00:55:42.160 --> 00:55:44.860
and making them available and making them browsable,
00:55:45.200 --> 00:55:45.300
right?
00:55:45.700 --> 00:55:46.060
So on the very,
00:55:46.240 --> 00:55:46.820
it's not top
00:55:47.020 --> 00:55:47.100
level.
00:55:47.260 --> 00:55:48.360
If you go to the first page,
00:55:48.560 --> 00:55:49.740
there's like a sidebar on the right,
00:55:49.960 --> 00:55:50.620
which gives you a lot of
00:55:50.840 --> 00:55:51.100
metadata.
00:55:51.540 --> 00:55:52.920
And one of the first few things is skills.
00:55:53.280 --> 00:55:55.360
And that gives you like a page on how to install
00:55:55.500 --> 00:55:56.440
these skills. So it's kind of like a,
00:55:57.000 --> 00:55:58.760
almost like a way not to just distribute,
00:55:59.060 --> 00:56:00.020
but a way to sort of
00:55:59.960 --> 00:56:01.020
like get ahold of skills.
00:56:02.100 --> 00:56:04.180
And there's a nice little sort of like disclosure there,
00:56:04.780 --> 00:56:05.280
install these skills,
00:56:05.480 --> 00:56:07.840
it gives you instructions on how to do such things.
00:56:08.380 --> 00:56:10.060
And you can just browse the skills below
00:56:10.380 --> 00:56:11.020
and see what's there.
00:56:11.110 --> 00:56:12.440
You might just take bits of them,
00:56:12.640 --> 00:56:13.180
make your own skill,
00:56:13.540 --> 00:56:14.200
or you might just say,
00:56:14.580 --> 00:56:15.260
no, these all look good.
00:56:15.460 --> 00:56:16.740
I'll just follow these instructions
00:56:17.040 --> 00:56:19.000
and install them for my project or globally.
00:56:19.750 --> 00:56:20.620
So we're trying to make that a bit easier.
00:56:21.080 --> 00:56:21.540
Yeah, it's super cool.
00:56:21.540 --> 00:56:21.720
Yeah, it's super cool.
00:56:22.490 --> 00:56:22.580
Yeah,
00:56:22.950 --> 00:56:24.540
that kind of brings me to the last thing
00:56:24.640 --> 00:56:27.640
that I wanna talk about is the AI-ification.
00:56:27.950 --> 00:56:29.500
And by that, I don't mean,
00:56:29.920 --> 00:56:32.660
How do I, are you using AI to write it or not?
00:56:32.740 --> 00:56:34.900
Like I imagine there's some degree of that or whatever,
00:56:35.160 --> 00:56:38.620
but if I am a person with a project package
00:56:38.920 --> 00:56:40.240
or something I want to document,
00:56:40.720 --> 00:56:42.440
AI is really good at going like,
00:56:42.490 --> 00:56:42.580
well,
00:56:42.740 --> 00:56:43.880
let me pull out all these pieces
00:56:44.760 --> 00:56:45.360
and then like,
00:56:45.560 --> 00:56:47.080
you know, sketch some stuff out for you.
00:56:47.580 --> 00:56:47.880
Is there,
00:56:48.600 --> 00:56:49.500
you know, and I can see now
00:56:49.550 --> 00:56:51.020
that you pointed me in the right direction
00:56:51.160 --> 00:56:52.440
that there's a whole AI section,
00:56:52.680 --> 00:56:55.060
like how do AIs work with great docs,
00:56:55.290 --> 00:56:55.400
right?
00:56:55.600 --> 00:56:57.620
And so you've got the llms.txt,
00:56:57.940 --> 00:56:59.380
which is really nice.
00:56:59.560 --> 00:57:00.420
you know, I referenced that before.
00:57:00.860 --> 00:57:01.920
People don't know there's an,
00:57:02.280 --> 00:57:04.420
this comes from, I believe from Jeremy Howard.
00:57:04.800 --> 00:57:04.980
Yeah,
00:57:05.240 --> 00:57:05.480
that's right.
00:57:05.720 --> 00:57:06.840
Yeah, we looked at this closely, yeah.
00:57:07.080 --> 00:57:07.240
Putting,
00:57:07.520 --> 00:57:08.200
yeah, so did I,
00:57:08.200 --> 00:57:09.380
and I find it super interesting.
00:57:09.660 --> 00:57:09.900
Like this,
00:57:10.060 --> 00:57:11.060
the idea is that if you,
00:57:11.460 --> 00:57:13.020
you know, there's a robots.txt
00:57:13.600 --> 00:57:15.060
and a sitemap.xml.
00:57:15.260 --> 00:57:17.380
These are standard web things on sites
00:57:17.540 --> 00:57:20.080
that humans rarely use to get any value from,
00:57:20.540 --> 00:57:23.200
but machines and traditionally search engines
00:57:23.700 --> 00:57:23.860
really,
00:57:24.080 --> 00:57:24.580
really do.
00:57:24.880 --> 00:57:26.600
And so, well, what do we put for AI
00:57:27.060 --> 00:57:28.460
to make it better, LLMs and so on?
00:57:28.600 --> 00:57:32.360
is this llms.txt file that describes in Markdown
00:57:32.640 --> 00:57:34.480
to the LLMs, like how you can better work with this.
00:57:34.700 --> 00:57:35.200
With that,
00:57:35.660 --> 00:57:36.500
you all have that, right?
00:57:36.620 --> 00:57:40.980
So you've got your llms.txt and the full one.
00:57:41.280 --> 00:57:42.460
You know, this is not something I'm doing.
00:57:42.600 --> 00:57:43.700
Maybe I need to do a full one.
00:57:43.800 --> 00:57:44.720
This one's interesting.
00:57:44.920 --> 00:57:45.420
It's a lot.
00:57:45.840 --> 00:57:47.880
So basically it's the entire bit of documentation
00:57:48.260 --> 00:57:49.320
distilled down, not distilled,
00:57:49.460 --> 00:57:50.500
but like written as one file,
00:57:50.960 --> 00:57:51.060
essentially.
00:57:51.260 --> 00:57:52.380
All doc strings mashed together,
00:57:52.640 --> 00:57:53.040
you might say,
00:57:53.380 --> 00:57:54.540
including guide material as well.
00:57:55.040 --> 00:57:55.720
So that's all in there.
00:57:55.840 --> 00:57:57.420
Yeah, and you've got these skills as well,
00:57:57.560 --> 00:58:00.460
which is looking super interesting and also a pretty neat,
00:58:00.840 --> 00:58:03.600
the CLI that you've created a couple of things on that.
00:58:03.880 --> 00:58:06.360
First of all, that it will actually install the skills.
00:58:06.880 --> 00:58:07.120
Yeah.
00:58:07.340 --> 00:58:08.960
So if you're an author,
00:58:09.340 --> 00:58:11.140
you would just use great docs,
00:58:11.340 --> 00:58:11.480
install,
00:58:12.020 --> 00:58:12.420
skill install,
00:58:12.660 --> 00:58:15.400
and then they may be the name of your library for other people.
00:58:15.480 --> 00:58:16.880
That's what other people would see on their sites.
00:58:16.880 --> 00:58:18.000
That's an interesting piece.
00:58:18.360 --> 00:58:18.740
Cause if I'm an,
00:58:18.940 --> 00:58:21.560
I have to admit, I haven't seen the skills piece a lot,
00:58:21.720 --> 00:58:23.840
but if I'm understanding rich too,
00:58:23.880 --> 00:58:26.500
this means great docs is also for like kind of all users,
00:58:26.760 --> 00:58:26.820
right?
00:58:26.960 --> 00:58:31.420
Like people who are interested in reading or consuming docs or using it with AI.
00:58:31.740 --> 00:58:32.220
Is that right?
00:58:32.400 --> 00:58:32.640
I see.
00:58:32.640 --> 00:58:34.480
So that's kind of where we're going more and more.
00:58:34.760 --> 00:58:34.900
Yeah.
00:58:34.900 --> 00:58:37.540
So it looks like you're really leaning into making great docs,
00:58:37.720 --> 00:58:38.580
something that works well
00:58:38.940 --> 00:58:42.040
if you're trying to generate docs and maintain with AI,
00:58:42.300 --> 00:58:42.440
right?
00:58:42.520 --> 00:58:46.040
We also want, if you point your agent at this site,
00:58:46.220 --> 00:58:47.380
it should be able to find these things
00:58:47.580 --> 00:58:48.000
pretty quickly.
00:58:48.240 --> 00:58:49.440
And you can actually like use tools.
00:58:49.860 --> 00:58:53.020
Like there's one called whatdoagentsc.runtime.app.
00:58:53.180 --> 00:58:53.700
Just search it up.
00:58:54.020 --> 00:58:58.600
You can put it in your URL and it'll show you what pieces are picked up by different agents.
00:58:58.780 --> 00:59:01.320
It actually simulates it really nicely.
00:59:01.760 --> 00:59:06.880
And I found that this sort of validated things that different agents do pick up LLMs.txt, LLMs.full.
00:59:07.320 --> 00:59:10.840
And there's other little pieces of metadata,
00:59:11.700 --> 00:59:16.480
things that go in the meta tag that can be picked up to like robots.txt and very accept,
00:59:16.840 --> 00:59:17.280
things like that.
00:59:17.940 --> 00:59:20.020
So we're working towards making this even easier.
00:59:20.320 --> 00:59:27.500
Like you just point at the site or point at any site that you author using great docs and your agent should be able to find things pretty quick.
00:59:27.760 --> 00:59:28.400
Very exciting.
00:59:28.820 --> 00:59:29.200
I love it.
00:59:29.300 --> 00:59:29.400
Okay.
00:59:29.780 --> 00:59:32.480
And also just you mentioned that there's the CLI,
00:59:32.780 --> 00:59:32.900
right?
00:59:33.060 --> 00:59:34.560
Or I don't know what I was mentioning.
00:59:34.980 --> 00:59:38.460
But the fact that there is a CLI is another really great enablement.
00:59:38.660 --> 00:59:44.620
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.
00:59:44.820 --> 00:59:46.520
Here's the docs and the skill.
00:59:47.060 --> 00:59:47.500
Make this happen.
00:59:47.820 --> 00:59:48.080
You know, right?
00:59:48.600 --> 00:59:48.720
Yeah.
00:59:48.900 --> 00:59:49.040
Yeah.
00:59:49.240 --> 00:59:50.280
And you can even,
00:59:51.020 --> 00:59:51.940
the skills I include,
00:59:52.220 --> 00:59:54.240
like in great docs could be used to author your
00:59:54.340 --> 00:59:55.120
own great doc site.
00:59:55.580 --> 00:59:59.700
Like there's all sorts of things in there for like just how it works and like, you know,
00:59:59.800 --> 00:59:59.900
like,
01:00:00.120 --> 01:00:00.860
like writing pages,
01:00:01.700 --> 01:00:03.960
they're kind of split up into like multiple name skills.
01:00:04.540 --> 01:00:07.160
So you can, you can just use that or make your own skills.
01:00:07.580 --> 01:00:07.660
Yeah.
01:00:07.700 --> 01:00:07.960
Very neat.
01:00:08.420 --> 01:00:08.600
All right.
01:00:08.700 --> 01:00:09.560
Two really quick things.
01:00:09.680 --> 01:00:11.120
I know we're pretty much out of time for you guys.
01:00:11.520 --> 01:00:11.840
One,
01:00:12.320 --> 01:00:16.080
what I get out of this is just a static site and I can just host it on any static
01:00:16.320 --> 01:00:16.840
site place.
01:00:17.240 --> 01:00:17.380
Okay.
01:00:17.740 --> 01:00:18.280
That's really good.
01:00:18.460 --> 01:00:18.840
For sure.
01:00:19.160 --> 01:00:26.040
it could be netlify it could be you know pages for me on provide some fine grained instructions
01:00:26.130 --> 01:00:30.100
for different uh hosts and things like that GitHub pages like seems like a nice default
01:00:30.780 --> 01:00:35.060
it's not you know but of course yeah netlify Vercel things like that we provide some hints
01:00:35.400 --> 01:00:40.340
that it works for me i i was running on netlify for a while but i actually had my monitoring
01:00:40.580 --> 01:00:45.199
software monitoring it and it actually went down surprisingly often i'm like why is my static site
01:00:45.220 --> 01:00:50.200
going down this makes no sense so i've ended up recently i've already got like a big server with
01:00:50.340 --> 01:00:55.480
tons of sites so i just i'll just have a config on nginx that just runs it you know and so there's
01:00:55.560 --> 01:00:59.420
a lot of options there yeah it's so interesting not not to dwell on it but i do remember you saying
01:00:59.600 --> 01:01:06.080
i think on a podcast with um hugo talking about your Hugo Van Kemenade your approach that you're
01:01:06.390 --> 01:01:11.599
you have way less downtime than even some of the cloud providers so not not to go too deep
01:01:11.620 --> 01:01:18.620
that's interesting to hear about let's it is i i could go for hours on this so be careful there
01:01:18.780 --> 01:01:24.720
michael i find it really interesting that you just the extreme simplicity of like i've got a server
01:01:25.200 --> 01:01:31.220
and either it's got a self-contained python and database runtime or it's just even a static site
01:01:31.410 --> 01:01:36.579
that goes a long ways you know really long ways instead of like all the 100 connected services
01:01:36.600 --> 01:01:39.300
powered by some dynamic thing underneath.
01:01:39.540 --> 01:01:41.600
And if one of them goes down, it takes a chunk with it.
01:01:41.780 --> 01:01:42.080
Yeah,
01:01:42.460 --> 01:01:42.500
yeah,
01:01:42.680 --> 01:01:42.960
for sure.
01:01:43.280 --> 01:01:44.320
Maybe that was my last question.
01:01:44.420 --> 01:01:48.460
I think just the deployment side of things is really interesting.
01:01:48.560 --> 01:01:49.540
So it sounds like just wherever,
01:01:49.940 --> 01:01:50.040
right?
01:01:50.240 --> 01:01:51.780
Anything that serves static files, you get to go.
01:01:52.000 --> 01:01:52.640
Pretty much, yeah.
01:01:52.820 --> 01:01:55.860
Because you get the site directory and you just go with that.
01:01:56.120 --> 01:01:57.620
Like it's complete site in a directory.
01:01:57.940 --> 01:01:58.180
Yeah, okay.
01:01:58.260 --> 01:02:01.600
So the second, now I remember, the second thing I wanted to talk about was
01:02:01.880 --> 01:02:04.380
if I go over to the user guide and I do a quick start,
01:02:04.720 --> 01:02:08.460
You show me the structure and I get this here,
01:02:08.880 --> 01:02:11.900
this yourprojectgreatdocs.aml, greatdocs, et cetera, et cetera.
01:02:12.500 --> 01:02:16.500
So it looks like the recommendation is to have great docs
01:02:16.760 --> 01:02:22.800
as a sub directory of your actual things that it is documenting.
01:02:23.160 --> 01:02:23.480
Is that right?
01:02:23.920 --> 01:02:25.220
Sort of, but you don't have to keep it.
01:02:25.380 --> 01:02:29.160
I mean, like it's just going to appear there when you render locally
01:02:29.540 --> 01:02:31.200
and you can look at the site, you can preview it,
01:02:31.580 --> 01:02:32.360
but you can just delete it.
01:02:32.500 --> 01:02:33.760
I can have it on CI or whatever,
01:02:34.160 --> 01:02:36.260
like on your CI system or however you're deploying.
01:02:36.320 --> 01:02:39.560
Like your step could be build and then copy and then delete.
01:02:39.990 --> 01:02:40.080
Yeah,
01:02:40.350 --> 01:02:40.440
exactly.
01:02:40.590 --> 01:02:40.720
The folder,
01:02:41.200 --> 01:02:42.840
not necessarily the YAML.
01:02:43.310 --> 01:02:44.080
Well, yeah, you want to keep that.
01:02:44.290 --> 01:02:44.420
Yeah,
01:02:44.570 --> 01:02:44.700
yeah,
01:02:44.860 --> 01:02:45.240
that's config.
01:02:45.660 --> 01:02:46.720
So that, commit that.
01:02:47.160 --> 01:02:49.200
And hopefully I sort of like outlined it here on this page,
01:02:49.350 --> 01:02:50.040
what should be like,
01:02:50.460 --> 01:02:50.600
you know,
01:02:50.860 --> 01:02:51.020
committed.
01:02:51.170 --> 01:02:52.820
And we automatically .gitignore some things too.
01:02:52.870 --> 01:02:54.020
So you don't accidentally commit things.
01:02:54.070 --> 01:02:54.660
You don't have to.
01:02:54.860 --> 01:02:57.360
If I want to do the freeze though, I probably have to keep it.
01:02:57.440 --> 01:02:57.520
Yeah.
01:02:57.780 --> 01:02:57.920
No,
01:02:58.080 --> 01:02:59.280
we actually work around that.
01:02:59.900 --> 01:03:01.580
So we do like a, like a pre.
01:03:02.000 --> 01:03:02.940
We got a little system there.
01:03:03.030 --> 01:03:04.400
So I know it wipes everything out,
01:03:04.510 --> 01:03:05.780
but we have a freeze mechanism
01:03:05.960 --> 01:03:06.840
that sort of works around
01:03:06.990 --> 01:03:09.100
this sort of like ephemeral nature of things.
01:03:09.470 --> 01:03:09.580
Yeah,
01:03:09.840 --> 01:03:10.440
still uses Quarto freeze.
01:03:10.840 --> 01:03:12.280
So it just does it a little bit different.
01:03:12.400 --> 01:03:13.400
Yeah, very interesting.
01:03:13.580 --> 01:03:14.980
Okay, final thoughts.
01:03:15.180 --> 01:03:16.060
People are interested in this.
01:03:16.070 --> 01:03:16.860
They want to get started.
01:03:17.280 --> 01:03:17.740
What do you tell them?
01:03:18.460 --> 01:03:19.280
Yeah, just check out the site.
01:03:19.610 --> 01:03:21.940
I'm hoping you'll be not wowed,
01:03:22.100 --> 01:03:24.080
but that it will resonate a little bit
01:03:24.300 --> 01:03:26.640
and the site should demonstrate what's possible.
01:03:28.640 --> 01:03:29.360
And again,
01:03:29.680 --> 01:03:30.000
like, you know,
01:03:30.360 --> 01:03:31.420
Even just like have your agent,
01:03:32.100 --> 01:03:33.560
like, you know, like have some AI,
01:03:34.020 --> 01:03:36.540
take a small Python package
01:03:36.610 --> 01:03:38.000
of yours and see what it could do.
01:03:38.350 --> 01:03:39.180
Take it for a little spin.
01:03:39.560 --> 01:03:42.020
And if there's anything that you think is missing or lacking,
01:03:42.180 --> 01:03:43.120
just drop me a line,
01:03:43.340 --> 01:03:43.420
like
01:03:43.580 --> 01:03:44.280
through the issues.
01:03:44.760 --> 01:03:45.040
That's like,
01:03:45.320 --> 01:03:46.340
that's basically it.
01:03:46.520 --> 01:03:48.160
Can I publish on read, read the docs?
01:03:48.540 --> 01:03:49.440
I don't think we have that yet.
01:03:49.960 --> 01:03:50.100
Yeah.
01:03:50.410 --> 01:03:54.720
I actually never even considered that as a, as a publishing point.
01:03:54.880 --> 01:03:56.780
One of the standard places to put docs,
01:03:57.190 --> 01:03:58.000
not necessarily required,
01:03:58.220 --> 01:03:59.320
but it's, it'd be interesting,
01:03:59.500 --> 01:03:59.680
you know?
01:03:59.880 --> 01:04:00.080
Okay.
01:04:00.200 --> 01:04:01.300
I'm going to log that down.
01:04:01.500 --> 01:04:01.980
That's already like,
01:04:02.140 --> 01:04:02.780
that's a good one.
01:04:02.980 --> 01:04:05.040
All right. We're rewriting the roadmap live here.
01:04:05.980 --> 01:04:06.080
Yeah.
01:04:06.400 --> 01:04:06.980
That's a toughie.
01:04:07.780 --> 01:04:09.640
You threw down the gauntlet,
01:04:09.800 --> 01:04:10.660
you know, this is it.
01:04:12.180 --> 01:04:12.680
Sounds good.
01:04:13.340 --> 01:04:13.740
Well,
01:04:13.980 --> 01:04:15.720
I really appreciate you both being here.
01:04:16.280 --> 01:04:16.420
Michael,
01:04:16.600 --> 01:04:19.660
you want to have a final word as well of inspiration for folks?
01:04:19.980 --> 01:04:20.620
What a great question.
01:04:20.980 --> 01:04:21.120
I,
01:04:21.740 --> 01:04:23.600
my, my final nudge might be like,
01:04:23.980 --> 01:04:26.900
we talked a lot about generating docs, the kind of technical activity.
01:04:27.400 --> 01:04:30.080
I do think there's this world of how do you write docs?
01:04:30.300 --> 01:04:31.680
Like what should your content be?
01:04:32.100 --> 01:04:34.280
And what should your sections of your doc site be?
01:04:34.660 --> 01:04:36.280
Obviously we're saying goodbye.
01:04:36.550 --> 01:04:37.020
So that's,
01:04:37.230 --> 01:04:38.500
we don't want to open that can of worms.
01:04:38.740 --> 01:04:41.420
But I just wanted to cast a light on that.
01:04:41.640 --> 01:04:44.800
That is a freaky big area on its own.
01:04:45.580 --> 01:04:46.720
I don't have great answers.
01:04:47.060 --> 01:04:49.520
So I'm just throwing some problems on people's laps.
01:04:49.960 --> 01:04:54.100
But I think that's a neat freaky area that is worth checking out.
01:04:54.500 --> 01:04:58.320
I think what you're doing is you're setting the stage for another episode in the future.
01:04:58.700 --> 01:04:59.160
Yeah, that's right.
01:05:00.540 --> 01:05:02.120
We're just trying to make it a three,
01:05:02.580 --> 01:05:02.840
you know,
01:05:03.160 --> 01:05:03.580
like a trilogy.
01:05:04.280 --> 01:05:07.080
So we're trying to get our third visit in.
01:05:07.660 --> 01:05:07.880
Perfect.
01:05:08.280 --> 01:05:08.520
All right.
01:05:08.570 --> 01:05:08.660
Well,
01:05:09.100 --> 01:05:09.300
Rich,
01:05:09.460 --> 01:05:09.560
Michael,
01:05:09.820 --> 01:05:10.440
thanks for being here.
01:05:10.740 --> 01:05:11.220
It's great as always.
01:05:11.540 --> 01:05:12.340
Thanks so much for having us.
01:05:12.640 --> 01:05:12.800
Yeah.
01:05:12.990 --> 01:05:13.080
Bye.
01:05:13.540 --> 01:05:13.700
Thanks.
01:05:14.940 --> 01:05:17.080
This has been another episode of Talk Python To Me.
01:05:17.350 --> 01:05:18.160
Thank you to our sponsors.
01:05:18.410 --> 01:05:19.660
Be sure to check out what they're offering.
01:05:19.870 --> 01:05:21.240
It really helps support the show.
01:05:21.840 --> 01:05:23.440
This episode is brought to you by Sentry.
01:05:24.200 --> 01:05:25.600
You know Sentry for the error monitoring,
01:05:25.760 --> 01:05:27.200
but they now have logs too.
01:05:27.420 --> 01:05:28.080
And with Sentry,
01:05:28.240 --> 01:05:30.200
your logs become way more usable,
01:05:30.720 --> 01:05:34.560
interleaving into your error reports to enhance debugging and understanding.
01:05:35.100 --> 01:05:38.260
Get started today at talkpython.fm/sentry.
01:05:39.060 --> 01:05:40.840
And it's brought to you by Temporal,
01:05:41.200 --> 01:05:42.460
durable workflows for Python.
01:05:42.880 --> 01:05:45.020
Write your workflows as normal Python code,
01:05:45.020 --> 01:05:47.320
and Temporal ensures they run reliably,
01:05:47.780 --> 01:05:49.500
even across crashes and restarts.
01:05:50.080 --> 01:05:52.820
Get started at talkpython.fm/Temporal.
01:05:53.280 --> 01:05:55.300
If you or your team needs to learn Python,
01:05:55.490 --> 01:06:03.500
we have over 270 hours of beginner and advanced courses on topics ranging from complete beginners to async code, Flask, Django,
01:06:03.900 --> 01:06:04.060
HTML,
01:06:04.540 --> 01:06:05.580
and even LLMs.
01:06:05.900 --> 01:06:06.280
Best of all,
01:06:06.520 --> 01:06:08.180
there's no subscription in sight.
01:06:08.740 --> 01:06:10.400
Browse the catalog at talkpython.fm.
01:06:11.100 --> 01:06:14.480
And if you're not already subscribed to the show on your favorite podcast player,
01:06:14.680 --> 01:06:15.760
what are you waiting for?
01:06:16.400 --> 01:06:18.200
Just search for Python in your podcast player.
01:06:18.290 --> 01:06:19.180
We should be right at the top.
01:06:19.580 --> 01:06:21.020
If you enjoy that geeky rap song,
01:06:21.210 --> 01:06:22.440
you can download the full track.
01:06:22.680 --> 01:06:24.500
The link is actually in your podcast below or share notes.
01:06:25.400 --> 01:06:25.960
This is your host,
01:06:26.180 --> 01:06:26.640
Michael Kennedy.
01:06:26.970 --> 01:06:28.100
Thank you so much for listening.
01:06:28.330 --> 01:06:29.120
I really appreciate it.
01:06:29.540 --> 01:06:30.260
I'll see you next time.
01:06:48.360 --> 01:06:49.460
of getting old.
01:06:50.920 --> 01:06:52.960
We tapped into that modern vibe
01:06:53.400 --> 01:06:54.360
overcame each storm.
01:06:55.180 --> 01:06:56.460
Talk Python To Me.
01:06:56.550 --> 01:06:57.840
I sync is the norm.
01:07:27.040 --> 01:07:27.060
Продолжение следует...