Adding API Documentation

[00:00:00]
>> The last thing we are going to do to this App is finish our quest for API documentation. So we already have this API extractor in place and that's whats giving, This nice API report. It's helping us make very deliberate and highly visible changes to our API surface.

[00:00:23]
So all that remains is for us to hook up this. This API document or tool. Let's begin by installing. Again, it's a work workspace dependency. This one's really easy. Oops, what's going on here? Sorry, it's Microsoft API documented now. I have a somewhat more complicated than normal script here.

[00:00:53]
We can just copy that into your scripts workspace folder. Now let me tell you what this is doing. This is an attempt to make sure that your API Doc's are always up to date, and that entails a totally fresh build, so that you pick up on everything. Right, you're not, you don't have out of date type information.

[00:01:13]
And you're building your docks off of stale build output. So we clean, get a fresh build. And then we run that api report and running this command this way instead of going dash, dash, local. Right? Running the command this way means that we will fail unless everything's up-to-date.

[00:01:39]
So you're not building API docs unless you've sorta given a thumbs up to any intentional changes you made to the public API surface. Now, GitHub Pages has recently advanced significantly. It used to be that you had to publish mark down or HTML, whatever you wanted to put on your GitHub page.

[00:02:01]
You had to put that on a special, Branch called gh pages. Now you can put it on any branch and potentially just in any folder you like. Now, the docs gets themed and there's a config yamo Yml file that says which theme you're using, so I detect if it exists.

[00:02:22]
And if it does, I move that file out of the way because we're about to blow that Doc's folder away and recreate it. And then later if we found that it did exist, we put it back And then in the meantime, between those two things, we run this api-documenter thing.

[00:02:41]
So we go yarn api-documenter. We want to generate markdown, and I'll talk about the other output option in just a sec. Our input folder is this root level temp folder containing all of these json files. And then the output folder is docs. I'm just going to make sure I don't have dogs around already.

[00:03:06]
So let's see. O think I have to do a couple more things to Ahmad. Make sure that script is executable. I have to make sure that I've wired it up in my package, JSON. So here I'll need API Doc's. And now it should be good to go. Let's see what happens.

[00:03:30]
So we're cleaning. We are now building everything from scratch. We have some build errors. What happened here. This is strange. Let's just try building it normally. You know what might be happening here? There we go. Now we're seeing the problem. So, I think when we do yarn, or TSC dash B packages it might, I don't think it's doing the layering up.

[00:04:27]
That we need for like that what learners doing, where it starts from the bottom and works at way up. Its way up. So let's try it learner run build. And I think there's something we could do to fix this. So if this works, we still have a problem All right.

[00:04:48]
I believe you. So, this is it's useful for you to for me to verbalise how I kind of deal with this kind of problem. So here's what I suspect I'm looking at this right we're in this data layer, and I am reading this information from another package, right, another local package.

[00:05:16]
I know what's going on here. Here you go. So here's where the error is happening. I see that I get this piece of type information and I don't get this piece of type information. What's going on. Well I wanna look at the decoration file. I wanna look at the types.

[00:05:36]
And I do notice that we've got potentially our beta somewhere in here. So this is not a publicly available method. So I can deal with this. And I'll show you how I would go about it here. So, back in my data folder, I basically want to say look, I want to use the beta things that are exposed from this package.

[00:06:04]
It is it is pretty simple to do. So, just need to go to this Ts config for the project. And it's a compiler option paths Slack types and we're just going to point it to node modules. Types sorry. This and then types beta, DTS. So I'm saying don't use the regular type information.

[00:06:43]
Use this file. And I have to say base URL is this folder. That should go away. All right now, nothing's picking up yet. First thing I want to do is restart my language server and let's see if this symbol comes through. Interesting Ts config. Let's look in this dist folder.

[00:07:18]
Alright, so there's the types Clearly, it's not coming through because we're looking at this declaration file. There's one more thing I could try here. No. I already have this I can get around this more easily by just making those no longer beta. I think part of the problem here is, I have two different competing lookup mechanisms.

[00:07:58]
On the one hand, there's no require resolve. On the other hand, there's This TypeScript composite project where I'm saying go and actually look at the source code, the TS files in this other project. So let's untangle that a bit by just saying, we're just going to expose the the API surface directly index.

[00:08:25]
And then all this stuff should just go away and be happy. And we may need another belt. Let's see. Looks good. All right, so that took care of it. Let's try the API docs again Much better. There is API extractor finishing each package. Okay, completed successfully. Look at our Docs folder got a bunch of good stuff in there.