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

[Gerrit0]

With 0.21, TypeDoc now has a --packages option, which I think could be used instead of entry points. It does the "main" resolution from package.json, handles monorepos that use npm/yarn workspaces, and just works better for most use cases...

[Zamiell]

I just wanted to give a huge +1 to this issue. Publishing typedoc docs to GitHub Pages via a CI action seems like the obvious go-to solution for virtually anyone making a new TypeScript library for other people to consume.

@cspotcode Is there any progress on this issue?

And in the meantime, can anyone suggest a non-official GitHub Action that accomplishes this kind of thing for a brand new typedoc user like me?

[cspotcode]

@Zamiell we haven't been focused on this lately, no. Personally I've been busy with #1634 and TypeStrong/typedoc-auto-docs

If you feel like helping out, please don't hesitate to get involved and we can offer guidance. You'd be helping out many other users, too.

The repository is here: https://github.com/TypeStrong/typedoc-action

I bet a lot of the code for a MVP could be copied from elsewhere. For example, we already publish ts-node docs here, so I bet you could copy-paste, simplify, and get something working: https://github.com/TypeStrong/ts-node/blob/main/.github/workflows/website.yml

[cspotcode]

@Zamiell feel free to chat with us on Discord, too. There is a #typedoc channel. https://discord.gg/typescript

[Zamiell]

I've now figured out how to use TypeDoc with GitHub Pages thanks to cspotcode.

You can tell GitHub Pages to either:

1. host the contents of your default branch's docs subdirectory, or
2. host the root contents of the gh-pages branch

(Option 2 is probably better.)

Option 1

The easiest way to deploy your TypeDoc docs to GitHub Pages is to choose option number 1.

First, generate the docs folder by running TypeDoc and commit it to your main branch.

Second, you need to configure GitHub Pages:

1. Go into your repository settings.
2. Choose "Pages" on the left hand side.
3. Select "Branch: main" and "/docs" as the folder.
4. Click "Save".

From now on, you should build the docs whenever you compile the project. For example, this is an example build.sh script:

#!/bin/bash

# Exit on any errors.
set -e

# Compile the project.
npx tsc

# Re-generate the documentation.
npx typedoc "src/index.ts"

echo "Success!"

You don't have to do anything in CI, because presumably you will be compiling the project as you go, and you will just push your docs changes to GitHub alongside actual code changes.

Option 2

Some people don't like option 1 because they don't like committing build artifacts to their main branch. It's annoying and/or confusing for people to see what code changed in the latest commit when they have to scroll past a bunch of documentation updates every time.

So, you can easily accomplish option 2 with something like the following:

# ci.yml file for GitHub Actions
name: CI

on: [push, pull_request]

jobs:
  build_and_lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v2

      - name: Retrieve the cached "node_modules" directory (if present)
        uses: actions/cache@v2
        id: node-cache
        with:
          path: node_modules
          key: node-modules-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Install dependencies (if the cached directory was not found)
        if: steps.node-cache.outputs.cache-hit != 'true'
        run: npm ci

      - name: Test to see if the project compiles
        run: bash build.sh

      - name: Perform automated checks
        run: bash lint.sh

      - name: Create the docs directory locally in CI
        run: npx typedoc src/index.ts

      - name: Deploy 🚀
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages
          folder: docs

This method doesn't require any changes to your repository settings, because since gh-pages is a special branch name, GitHub will automatically pick it up and deploy it to GitHub pages without you having to specify another additional.

[Gerrit0]

Tip for option 1 - TypeDoc can emit code just like tsc does in this simple setup.

# instead of
tsc
typedoc src/index.ts
# you can do
typedoc src/index.ts --emit

However, option 2 is the way I would recommend doing this. It is roughly what TypeDoc itself does for publishing the site, though TypeDoc's config is slightly more complicated due to running typedoc on itself

[jbottigliero]

I encountered this issue recently transitioning to GitHub pages and wanted to flag a few updates that might be relevant. GitHub has made (and is making) some improvements to Github Actions + GitHub Pages, so much so that it could make providing "zero-config publishing" a matter of providing documentation for existing actions (or creating a pass-thru implementation).

⚠️ Official support for building Pages with Actions is in public beta at the moment.

Noting the above, I've found success with the following:

name: "typedoc"

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      # Generate your TypeDoc documentation
      - run: npx typedoc
      # https://github.com/actions/upload-pages-artifact
      - uses: actions/upload-pages-artifact@v2
        with:
          path: ./docs  # This should be your TypeDoc "out" path.
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        # https://github.com/actions/deploy-pages
        uses: actions/deploy-pages@v2

I see this as a GitHub-official version of Option 2 above.

[erikyo]

I've created tsdoc-action for using this wonderful repo with the github action, I hope it is well equipped with what is needed but advice and feedbacks are welcome. Give it a go and share your feedback—it would be awesome!

[Gerrit0]

With GitHub's deploy pages workflows now, I don't think it actually makes sense to make a custom action that then needs to be maintained separately -- @jbottigliero's example is exactly what I'd recommend to people looking to deploy TypeDoc with GitHub actions, and https://github.com/actions/starter-workflows/pull/2255 will even add an example (which mostly matches this, bit of extra stuff that seems kind of weird to me) to GitHub's starter templates.

For even simpler usage, https://tsdocs.dev/ is built on top of TypeDoc, and automatically generates docs for you from your code comments.