API Documenter

[00:00:00]
>> Mike North: Next we're gonna take the output of API Extractor and use it to make some simple API documentation for our models monorepo package. This is quite simple. We first need to install API Documenter if it's not installed already. Let's check, @microsoft/api-documenter. And doing this within the models package is right.

[00:00:32]
Great. Dependency added. Now I'm going to run pnpm api-documenter markdown -i for input temp -o for output docs. So we're saying I wanna invoke api-documenter. I want my docs in markdown. The other option here is a YAML file which you can feed into other documentation systems like docusaurus.

[00:01:02]
I've personally never figured out how to do that, but it is just a matter of aligning those two formats and then pointing to this temp folder, right? So if you customized where this temp folder was being stored, you would wanna keep that consistent. And this by the way, is something you don't want to commit to git.

[00:01:23]
So while we're saying that, let's go to our gitignore. Make sure we're ignoring that, temp save. We wanna see that get grayed out, perfect. And then the output folder is docs. Let's let it run. Great. Deleted the old output from docs. Well, none was there. And then what was written was a new seeds models package.

[00:01:54]
Look, a bunch of markdown files. Let's look at our index.md in VS Code, get rid of that. You can see here how if we had more than one library, you could lump these things together and you could have like all of the different packages you might have in your monorepo.

[00:02:14]
And then clicking into one of those, you can see. All right, we've got like a seed packet collection model. There wasn't a lot of commenting here, but this is all just coming from code comments seed packet model. Here are the different types and the description. This is all derived from comments and type information.

[00:02:36]
So particularly if you're using this mostly for internal purposes, it's kind of nice to have this in here. You can browse this right within VS code. You don't have to go to some other docs website. You don't have to switch out of this tool. I really like the idea, particularly if you're not making this a product and you really care about the visual appearance of the docs greatly.

[00:03:04]
These end up being just a very browseable thing if there happen to be code. Comments on things that gets percolated through. But mostly it's type information and it does have a nice sort of multi page structure where you could easily track the changes to things over time. So that's another aspect I like about this.

[00:03:28]
If you check this into git, this lets you look at the history of these things over successive builds and you can see them as almost like a time machine of the surface without having to worry about the implementation and refactoring within the methods. It's a nice distilled piece of information there.

[00:03:54]
So this is API Documenter.