Using @microsoft/api-extractor to generate documentation

[johnhooks]

I saw in the GitHub projects that there is interest in using @microsoft/api-extractor to generate the api documentation. I am interesting in learning how it works, and I have started playing around with it in a scratch project. Would working on implementing api-extractor in Dinero.js be something that is helpful?

[sarahdayan]

Absolutely, feel free to PR :)

[johnhooks]

Have you used api-extractor before?

Before trying to add it to a mono repo, I decided I should get it working in a smaller package of mine. It's definitely very powerful.

Using it seems to have a few main hurdles:

1. Configuration (not too bad, but will add a few new config files to the project, api-extractor.json, it will need to be in each package of Dinero.js but it can be extended, similar to tsconfig.json).
2. Add release flags to all comments of exposed functions. Also, check that all comments fit the TSDoc format.
3. There will need to be some new steps in the build process, tsc needs to be run to create the declaration and map files used by api-extractor. Then api-extractor is run and generates files that are used to track api changes and generate documentation.
4. api-extractor can rollup the declaration files, is this something you would like it to do?
5. Lastly the markdown generator will need to be configured to integrate with the Dinero.js website.

[sarahdayan]

Never set it up myself, no.

api-extractor can rollup the declaration files, is this something you would like it to do?

Yes, it's a good idea to have a single declaration file instead of what we have right now.

Lastly the markdown generator will need to be configured to integrate with the Dinero.js website.

What's this part for? If we can have a JSON file instead (I think it's possible) which we can then leverage in the site with MDX, it's better.

Feel free to start a PR and we can discuss and make decisions over there directly.

[johnhooks]

Will do.