Typedoc: Official Github Action for zero-config publishing to GH Pages

[cspotcode]

Search Terms

github action
github actions

Problem

Github projects should be able to get rendered typedoc published to Github Pages with as little configuration as possible.

Suggested Solution

Relevant Discord conversation:
https://discord.com/channels/508357248330760243/640177505915109377/803749658937131058

Create a dedicated GH Action, for example TypeStrong/typedoc-action, which can render most well-behaved TS projects and push the results to GH pages. The goal is zero configuration required, but flags can control:

• branch and subdirectory where the docs are pushed
• Does publishing overwrite existing branch or merge contents with that's already there (e.g. play nice with docusaurus, or push to a subdirectory of main branch)
• enable pull requests and/or topic branches to publish to subdirectory URLs, e.g. https://myorg.github.io/myrepo/pull-requests/123

Minimal setup might look like this:

# .github/workflows/docs.yml
on:
- push
jobs:
  build:
    steps:
    - uses: actions/checkout@v2
    - uses: TypeStrong/typedoc-action@v1
      with: repo-token: ${{ secrets.GITHUB_TOKEN }}

[Gerrit0]

I like the idea!

Some questions:

• Does this require that TypeDoc is a dependency? (npm at least doesn't play well with peer dependencies installed with npx)
• Should popular plugins (e.g. typedoc-plugin-markdown) be available by default? Extra option?
• In my experience, actions don't get upgraded unless something breaks... does this need a new update for every patch of TypeDoc? How can it encourage people to upgrade?

TypeDoc's output scheme currently will always wipe out the output directory (unless an option is passed so we don't do any checks and just overwrite necessary files) - we don't do merging, and it's hard to do... detecting a file that should be deleted is impossible without some kind of build info file.

[cspotcode]

I think the Action should be fully automatic while still allowing the user to customize. In that spirit, here are my personal opinions:

• it should respect the version of typedoc in your package.json / package-lock.json / yarn.lock but otherwise install and run latest from npm, whatever that may be at the time it executes.
• Either a) have optional flag to set typedoc version, or b) write docs instructing users to add typedoc to package.json to choose version
• Use latest versions of popular plugins by default, but if typedoc is in your package.json, then only use plugins declared there
• Respect tsconfig.json or typedoc.json if they exist, otherwise use defaults

TypeDoc's output scheme currently will always wipe out the output directory

I was thinking more in terms of merging typedoc's output with the contents of the gh-pages branch that may have come from other tools. For example, suppose you have a separate step which publishes a docusaurus site to gh-pages, (only when certain markdown files change) or you have a manually committed HTML site, but you also want typedoc to render into an api subdirectory of the gh-pages branch. "Merging" means deleting and replacing the contents of the api subdirectory without touching anything else in the gh-pages branch.

[wojpawlik]

It's already possible to deploy typedoc-generated docs to GitHub Pages. Therefore, TypeStrong/[email protected] should focus on simplicity and reliability, not on fitting every workflow.

Docs should be built by running yarn run typedoc --out /tmp/typedoc/build. It works in projects using npm too!
As long as this continues to work, the action won't require updating for new typedoc versions.

The command will fail if typedoc is not installed, which is good for reliability (typedoc@0 gets breaking changes).
Users need to npm install --save-dev typedoc and any plugins they need, and specify entryPoints in typedoc.json.

We should reuse an existing action for publishing. It even allows specifying TARGET_FOLDER.

[Gerrit0]

typedoc.org does something similar for building + publishing automatically... a bit more complicated since it has to run on itself.

I think I like being more restrictive for the version/plugins, at least initially. Every minor upgrade of TypeDoc in the past year has contained breaking changes. If the user hasn't installed what they want, erroring out seems appropriate.

Not all plugins contain options to turn them off - so just installing some plugins will make changes to how typedoc runs (e.g. typedoc-plugin-markdown will prevent html generation from occurring)

However at this point, is a TypeDoc specific action that useful? 7 lines in the action @wojpawlik posted to do what this action would do... is bundling build+deploy into a single step helpful?

[balupton]

We used github pages originally, then moved to surge, which we deploy via this github action https://github.com/bevry-actions/surge with deployments for branch, commit, and tag

We automate our entire package configuration via https://github.com/bevry/boundation (the github actions release will be coming in the next few weeks)

[cspotcode]

I think it's still important to offer a fully automatic option for users who want batteries included in the language's ecosystem. For those users, choosing what it looks like and where it's hosted are not important, and the prospect of configuring anything is enough to prevent it from happening. It is the ecosystem's responsibility to offer a default that makes those pragmatic choices. To them, docs should be built-in, and the need to configure anything is considered a deficiency of the ecosystem when they compare it to other languages. Those users might reasonably argue "It's 2021, I wrote perfectly valid code and put it on git, why is that not enough to get API docs? Why are you asking me to add dependencies and commands and another config file?"

godoc is an example. If godoc's package registry knows the URL of your git repo, you get docs. Full stop, no need to do anything else.

I think our ecosystem should push in that direction, whether or not "typedoc -> GH Pages Action" is the correct way to do it. This is of course not forcing anyone to use zero-config, but making the option available. I think this is one way to step in that direction.

[Gerrit0]

I'll buy that!

True zero config means a couple extra things:

1. We need to automatically install typescript if not installed (easy?)
2. We need to automatically discover the entry point (easy for Node, a bit more convoluted for TS projects with outDir)

[wojpawlik]

typedoc CLI could default entryPoints to ['src/index.ts'].

I doubt 0conf is attainable before [email protected]. I don't think there's a good version to default to.

[cspotcode]

What if, in the first-pass prototype of this GH Action, entrypoint is the only required config option? Is that an acceptable approach to move forward with the idea, and then we can improve over time?

Do any of these 3 options sound reasonable for a first-pass prototype of this idea?

• in the docs, provide a .github/workflows/typedoc.yml that can be copy-pasted into your repo, and within it, it has an entrypoint specified. If the user copy-pastes it, they have not configured anything, but it is also fairly obvious how they can change the entrypoint config
• ask users to copy-paste "typedocOptions" {"entrypoints": [...]} into their tsconfig.json. Not ideal but easy enough
• Default the entrypoint to "index.ts(x)" or "src/index.ts(x)" if either exists.

[Gerrit0]

I'd be happy with either the first or the third option, though for the third option we probably need to be a bit smarter - look at package.json "main" and tsconfig outDir if present

[cspotcode]

First seems easiest since it's a one-to-one between the Action option and the typedoc CLI flag.

[cspotcode]

I started jotting down ideas in code.

https://github.com/TypeStrong/typedoc-action

If anything about this is wrong at all, wrong repo location, anything at all, please let me know. I find it helpful to think through ideas in code, which is why I started writing. But I'm not trying to railroad the project in a particular direction.

[Gerrit0]

You're not alone in that!

I'm not sure about a single args: parameter for the action to contain all values... there's something that feels off about it.
I think it might end up being cleaner to use TypeDoc's API than to use spawn or exec to call it... https://github.com/TypeStrong/typedoc/blob/master/bin/typedoc