Optimize generated reference docs for launch

[mikelehen]

Right now our generated reference docs (https://act-now-packages.web.app/docs/index.html) aren't the best.

• I disabled typedoc's monorepo support in Reenable typedoc with workarounds to avoid out-of-memory crash. #399 because it was contributing to out-of-memory crashes. This made it format less nicely (looks like all the code lives in one big package).
• The formatting is very plain. We'll want to theme it to make it match Act Now branding.
• Maybe more. I haven't looked that closely at the usability of the docs.

Ideally we'd have very approachable docs, like e.g. Material-UI. https://mui.com/material-ui/api/grid/

We should:

1. Look around to see if there are other tools we could use besides TypeDoc. E.g. what does Material-UI use? Note that it'd be nice to keep using a tool that is TypeScript-aware.
2. See if TypeDoc's monorepo support works better now and could be reenabled.
3. Investigate theming ability, etc. with TypeDoc to see what's possible for improving docs.

I'd try not to spend more than 1-2 days investigating this initially, especially if we find out there are other tools we should be considering. We can discuss options / recommendations at standup.

[mikelehen]

https://api-extractor.com/ is another option for generating docs (from Microsoft) but it seems much more strict / opinionated and less widely used. I played with it a little and had trouble getting it to run. The builtin documentation generator just generates markdown. I think it'd probably require a lot of work / customization to use.

[mikelehen]

I'm not very happy with the options that I've found...

I think TypeDoc and API Extractor are the only real options for API Documentation for typescript projects.

• API Extractor is part of rushstack, created by Microsoft. I had trouble getting it to run on our codebase (it works completely differently than TypeDoc, running on the generated .d.ts files) and I think it might require a fair amount of work / customization to use. That said, I do like the formatting of the rushstack docs [generated by api-extractor I assume] better than TypeDoc. Though I think the out-of-the-box support only does markdown, so not sure how much custom work would be needed.
• TypeDoc is okay, but the (default) output isn't very friendly / usable IMHO, and it has a number of quirks. The output for react components is pretty poor (though not sure API Extractor would be any better).

I think we will probably want to use one tool for generating our "normal" API reference docs (regions, metrics, etc.) and another tool for documenting our react components (everything in ui-components), so that we can get nice clean documentation of the properties for each component, without having to navigate intermediate interfaces (MetricCompareTableProps or whatever).

For documenting react components I've found:

• Storybook has a "Docs" page for each component that shows the props table, but it has 2 problems: 1) It's a separate page that you have to click on. There's no way to just browse all the component docs directly. You can't even link directly to a docs page AFAICT. 2) By default it is interactive, so you can change the prop values. In theory this could be useful, but in practice it is super messy since many of our components take complex props (like a list of regions that aren't conducive to storybook's UI).
• React Styleguidist is similar to Storybook and also supports including component documentation, but it wasn't trivial to set up (you need to setup webpack) and I don't think we really want to switch away from Storybook. Using both seems odd.
• react-docgen-typescript is an underlying module built for react styleguidist but it is also used by Storybook for extracting React component docs from TypeScript and it seems pretty easy to use. We could probably build something on top of that if we wanted, but that would be more custom work.

I feel like to have good docs we're probably going to need to do some deeper investment / custom work that could include:

1. Playing with react-docgen-typescript to generate our own docs for our react components.
2. Playing with typedocs plugin / theming infrastructure to see if we can improve the output. Perhaps even integrate with react-docgen-typescript to create decent docs for react components.
3. Trying harder to get api-extractor working to see if we can generate better docs with it than with typedoc.