wip: initial commit for rocket

[bennypowers]

This PR implements the docs site using rocket and 11ty

The API docs pull in typescript definition files from atom-ide-base, run them through TypeDoc, then process the resulting "reflection JSON" with 11ty nunjucks templates and filters.

to run:

npm ci
npm run typedoc
npm start

Goals

• bootstrap rocket
• generate docs from .d.ts
• brand colours
• dark mode
• move more of the <type-doc> styles to light DOM

[bennypowers]

The approach I'm taking is to run typedoc in json mode against the atom-ide-base package, then render API docs for the types using nunjucks.

Before launching, we should update the typings in that repo to use tsdoc comments, so as to include the (markdown) descriptions in the API docs.

in terms of styles, I haven't started working on the CSS yet, by I'm aiming for something along the lines of this:

[aminya]

This looks great so far. Thanks! 🎉

[bennypowers]

Today's progress:

The blurbs and screenshots here are open to changes. I was not focused on content authoring, instead on code

The more use we make of tsdoc in our typing files, the nicer these pages will look. All those strings come straight out of the `.d.ts`. It would be totally rad to have function parameters documented inline, as well.

[bennypowers]

from

/**
 * `atom-ide-busy-signal` service.
 */
export interface BusySignalService {
  /**
   * Activates the busy signal with the given title and returns the promise
   * from the provided callback.
   * The busy signal automatically deactivates when the returned promise
   * either resolves or rejects.
   * @typeParam T return type of the async function
   * @param title name of the busy signal to activate
   * @param f Async function. When the promise resolves, the signal deactivates.
   * @param options options for this signal
   * @returns A promise which resolves with the type of `f`
   */
  reportBusyWhile<T>(title: string, f: () => Promise<T>, options?: BusySignalOptions): Promise<T>

  // ...
}

[daKmoR]

grabbing data directly from the typescript definition files sounds like a very good idea... e.g. no chance that the data get's out of sync.

Additionally the site looks nice 👍 and adding type docs will now improve typings and website at the same time... what a sweet deal 💪

Awesome progress 🎉

[illright]

Very nice looking so far. I find the red color slightly intimidating, maybe we should opt for the brown color of the logo as our accent color?

Also regarding the last screenshot of the method docs, could we write out the entire signature of the method in that blue header? I find it easier to first visually grasp the entire signature (i.e. reportWhileBusy<T>(title: string, f: () => Promise<T>, options: BusySignalOptions) and then read into what every parameter does.

And also it'd be great if things like BusySignalOptions were hyperlinks to quickly jump to the relevant interface.

Good job!

[bennypowers]

maybe we should opt for the brown color of the logo as our accent color?

Nice idea. I haven't touched the styles that much yet.

write out the entire signature of the method in that blue header?

Some of the signatures (e.g. the one you mentioned) can be quite long, so putting it in the header might have unintended effects on layout. WDYT about using a <details> element in the card body?

hyperlinks to quickly jump to the relevant interface

I have a plugin for this, but I'd prefer to implement it after solving modernweb-dev/rocket#42. cc @daKmoR. If you all have some ideas how to solve that one, PTAL over there.

[bennypowers]

@aminya does atom-community have a netlify account? PR previews can facilitate discussion and development.

[illright]

WDYT about using a <details> element in the card body?

Don't think it'd be as helpful but I see what you mean by the length. In that case, maybe we could omit the types and simply write out the argument names in the headers?

[aminya]

@aminya does atom-community have a netlify account? PR previews can facilitate discussion and development.

I made one. However, running pnpm install && pnpm build results in an error.

[aminya]

This looks good to me.

@bennypowers Feel free to merge whenever you think this is ready

[bennypowers]

There's a few loose ends I want to tie up before merging. Asides from that the type signatures will still need some work to cover all cases, so check your expectations :D. we should iterate on more content, too.

[bennypowers]

@aminya regarding pnpm not found in the build, see https://answers.netlify.com/t/using-pnpm-and-pnpm-workspaces/2759

[bennypowers]

and when we merge, we should either set up the pnpm build in github pages or just use netlify to host the site

[aminya]

Can we just use Github pages? I don't see any benefits in using Netlify.

and when we merge, we should either set up the pnpm build in github pages or just use netlify to host the site

Adding a step to upload the built file to the GitHub pages should be easy.
We already have bought our domain. We should probably use that eventually.

[bennypowers]

I don't mind either way, although I do like the deploy previews feature of netlify it really helps reviews

[aminya]

There is the same thing for GitHub Actions:
https://github.com/JamesIves/github-pages-deploy-action

I believe you can use ${{ github.ref }} to adjust the branch it deploys the website to

name: Build and Deploy

on:
  push:
    branches:
      - master   # Only on master now

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2

      - name: Setup PNPM
        uses: pnpm/action-setup@master
        with:
          version: latest

      - name: Install and Build 🔧
        run: |
          pnpm install
          pnpm run build

      - name: Deploy 🚀
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: public # The folder the action should deploy.