-
Notifications
You must be signed in to change notification settings - Fork 710
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Official Github Action for zero-config publishing to GH Pages #1485
Official Github Action for zero-config publishing to GH Pages #1485
Comments
I like the idea! Some questions:
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. |
I think the Action should be fully automatic while still allowing the user to customize. In that spirit, here are my personal opinions:
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 |
It's already possible to deploy Docs should be built by running The command will fail if We should reuse an existing action for publishing. It even allows specifying |
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? |
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) |
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. |
I'll buy that! True zero config means a couple extra things:
|
I doubt 0conf is attainable before |
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?
|
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 |
First seems easiest since it's a one-to-one between the Action option and the typedoc CLI flag. |
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. |
You're not alone in that! I'm not sure about a single |
With 0.21, TypeDoc now has a |
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? |
@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: 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 |
@Zamiell feel free to chat with us on Discord, too. There is a #typedoc channel. |
I've now figured out how to use TypeDoc with GitHub Pages thanks to cspotcode. You can tell GitHub Pages to either:
(Option 2 is probably better.) Option 1The easiest way to deploy your TypeDoc docs to GitHub Pages is to choose option number 1. First, generate the Second, you need to configure GitHub Pages:
From now on, you should build the docs whenever you compile the project. For example, this is an example #!/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 2Some 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 |
Tip for option 1 - TypeDoc can emit code just like tsc does in this simple setup.
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 |
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).
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. |
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! |
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 actions/starter-workflows#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. |
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:main
branch)https://myorg.github.io/myrepo/pull-requests/123
Minimal setup might look like this:
The text was updated successfully, but these errors were encountered: