Rendering API Documentation

[00:00:01]
>> So I'm gonna push this and I wanna show you what it looks like, rendered in GitHub. And then we'll just take a quick look at GitHub pages and how that presents itself. And that will be it. There we go some docs. All right. So looking at the index markdown file in here, that's the entry point.

[00:00:25]
And what we get some like, obviously not a super relevant picture to have here. I simply am making a point here about How you can duck how this may seem like a basic tool, but you have the ability to use a limited subset of HTML, approximately the same subset of HTML you can use with GitHub flavored mark down.

[00:00:49]
And so you could document each of your packages here. So if we were to click into one of these, so you've you've got like This here this was an I think an h3 or something like that. And you can see we can use like backticks. I deliberately created some of these links.

[00:01:06]
Here's the link to front end masters, right. So we've got functions clear indications of beta. This is linking to other entities using jazz stock syntax. So I could just go straight to AI channel, and it would take you to the right place, go to iMessage take you to the right place, right.

[00:01:25]
Even each of these little things has their own page. So you can have some great examples right in your API documentation. In your comments, and it'll all be rendered where it needs to be rendered. Now, GitHub Pages we can point to. I find that little section here. So I could say the source for GitHub Pages is front end masters and let's look at the docs folder.

[00:01:57]
Save. And I wanna show how it keeps you up to the top of the page. Let's use like this slate theme you can pick whatever you like, select theme. All right, so now what it's doing while we wait for it to build just to recap, I just simply said front end masters the branch is FEM Look on the FM branch in this dog's folder.

[00:02:25]
We've chosen a theme here it's saying we've selected this slight theme, and then eventually up, I mean already this is popping up. Now the theme for some reason for me on the first render of this page, it's always this index page doesn't pick up the theme.It will after the next commit, which I can do, I can do real quick.

[00:02:53]
I found a little bug that shouldn't be showing as an h3, But when we drill into it, it's rendered. So let's see if we can, we can go fix that. So you have the ability, you have a lot of flexibility to write your own content, like you could write a little guide, right?

[00:03:12]
And then you have table of functions and you can click here and It's it's pretty nicely formatted syntax highlighting around code code examples, right? Just because I use the same thing I use in markdown tagged code fences, like, tick, tick, tick, Ts. That's how we get this. Right.

[00:03:32]
So a lot of nice features without having to do anything complicated and it's the same stuff. Write the same stuff that is enriching your existing VS code tooltips. So if we were to look at teams, and we were to look at this type guard that we're passing in somewhere.

[00:03:56]
His team so this could use some love here to get the syntax highlighting properly, but it's the same information and this is what's creating that nice little link To an entity and another package, get team by ID. So if I were to document this real quick ID of team to fetch, get a team by ID.

[00:04:24]
And up here instead of this, I would say, Link slack. Teams or types, ITeam, save. GetTeamById. Right, and now, generate those API docs again. It's gonna create a fresh build. It's gonna extract that API surface. In this case, it's gonna just sort of forcefully approve Make sure Yep.

[00:05:03]
So we have this dash dash local things. So it's just going to say, whatever I find I'm just going to use and so it'll get that API surface. It will use that as the input for the documentation and then we end up with some different markdown some small changes to the markdown update docs and a push.

[00:05:30]
Oops, git pull. A reason I have to do this is GitHub added that config file for my GitHub Pages. Got to pull that in, make that merge, commit and push again. And what we can see if we go back to our project real quick GitHub actually models this as a deployment now.

[00:05:59]
So if we click on we go back to the front end masters branch. And there's a little status here. There's GitHub Pages so it's telling me like I'm in progress. I'm building your ducks etc, etc. And now we should see, that was in the data layer. Get team by ID.

[00:06:24]
There we go. So there, now I'm linking to assemble in another package. I'm going across mono repos, and it just works. Right, everything gets wired up really, really nicely. Pretty cool stuff, even this symbol down here. promise that resolves to an iTeam. I think this is this is not the most rich documentation feature set that I've seen.

[00:06:48]
But it is good, where it's most important to me that a solution be good. Low effort, stitching together many packages in a mono repo with minimal effort. The only thing we had to do that's sort of a little tricky is get all those JSON files into one folder.

[00:07:07]
And then you just say okay, build me docs for everything in this folder. That's not so bad. Right, but but this, this is a great doc solution for this kind of thing.