Spike how we can integrate information from Typedoc in our own docs

[romaricpascal]

What

Spike to discover:

• which informations on our API Typedoc can provide us in a format we can then integrate in our docs (hopefully JSON or similar machine parseable format)
• how we can integrate that information in the frontend docs
• what this automation would mean for authoring/reviewing the content of the API docs

Why

So we can automatically generate part of our API documentation in our docs

Who needs to work on this

Developers, Tech Writers

Who needs to review this

Developers, Tech Writers

Done when

We've identified:

• [x] Information Typedoc gives us access to
• [x] How we could integrate it in the frontend docs
• [ ] The impact on authoring/reviewing the API docs

[romaricpascal]

We currently integrate our Sass API doc automatically, so there may be interesting bits to take away from there (thinking of the authoring/reviewing).

[owenatgov]

I looked at this very briefly today. The hope is that we can export our js API via typedoc the same way we do with sassdoc.

How our sass API is generated via sassdoc

This is mainly driven by the build:sassdoc and build:sassdocv4 commands which are both run by the postinstall command. These can all be found in the package.json. The build commands are just running sassdoc but specifying the entry point as within the govuk-frontend package and the output as a json file. In the index for the Sass API reference page it interprets this json data, with the help of the sassdocs_helpers module. At this stage it's data interpolation and feels very possible.

How we might generate our JS API via typedoc

Typedoc has similar functions for specifying an entry point and an output location as json. It looks like it might be a bit more involved though. The cli won't run without a valid config and we don't distribute our one in govuk-frontend. We can either replicate it in the frontend docs or try exporting it. There may be a need to redo some of our paths so the former option might be better, if a bit of a drag.

[owenatgov]

Update

After spending all this week tweeking and trying stuff, we managed to finally get a typedoc of govuk-frontend produced from within the frontend docs 🎉 Click here to see the test branch.

The main takeaway is that there are a few things we don't export in govuk-frontend that result in typescript raising type errors. Notably we have comments in our code where we ask ts not to emit an error, but these aren't being read in the package because we don't include comments for methods marked as private. Because of this, we were only able to produce a typedoc using typedoc's --skipErrorChecking flag.

Additionally, because we don't include which methods are private in our built package, typedoc isn't able to distinguish between public and private methods.

Next steps

We're going to take the following into a more final implementation:

• Maintain the tsconfig built during the spike
• Update govuk-frontend's output on package build to keep methods marked as @private and @ts-expect-error comments in the package module files (but not the bundles)
• Continue using the --skipErrorChecking flag in any future build commands

In addition, we're going to further investigate the following:

• Why our methods are listed as 'external' by typedoc and what this means for us
• How to mitigate risks of the frontend docs not building when a new version of govuk-frontend is published in case an unforseen ts error is flagged

[romaricpascal]

Going to close this spike as the work on it is over. We can look further into this as we tackle #5227