Feature: Add a GitHub Actions workflow for documentation site deployment.

[prjctimg]

This issue came from this pull request which failed to pass build tests. It would be nice to have a workflow that logs the deployment results where everyone can see them (in the Actions tab)

[prjctimg]

So I've found this tool called tsdoc-markdown which can generate documentation from Typescript source files.

The tool also has a workflow file to automate the build when we do a PR.

The docs can then be pushed to the docs repository therefore triggering a redeployment on the site.

Here's the repository

@takanome-dev Any idea how we can make such a workflow?

I'm configuring the build process and will do a PT shortly.

[takanome-dev]

@takanome-dev Any idea how we can make such a workflow?

First, try it locally and make a script to generate the docs.
Then, add a new job after build in development/yml:

docs:
    runs-on: ubuntu-20.04

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Install dependencies
        run: npm ci

      - name: Generate docs
        run: npm run docs

      - name: Commit docs
        uses: EndBug/add-and-commit@v9
        # We don't want to commit documentation changes to main
        if: ${{ github.ref != 'refs/heads/main' }}
        with:
          add: .
          default_author: github_actions
          message: '🤖 Documentation auto-update'

Edit: Oh wait... 🤔

We will need a new workflow file which will only run if the generated docs folder changes and then deploy to Vercel. You can copy deploy to vercel job from the docs

[prjctimg]

takanome-dev I have been reading around and came across "workflow triggers" .

Would it be easier to move the documentation generation to the docs repo ?

[takanome-dev]

From tsdoc-markdown

Generates markdown documentation from TypeScript source code. Useful for generating docs from code and injecting automatically the outcome into project README files.

Will we be able to generate docs if there are no ts files?
Also, why separate the docs from this repo?

[prjctimg]

Good question @takanome-dev

I've been considering this as well given the obvious disadvantages I'm seeing of seperating the two right now.

I had split the docs because I was failing to configure nextjs to share the repo alongside my code.

If you're suggesting that we unite the docs and code together I'm 💯 with you.

[prjctimg]

Are you suggesting we use GitHub pages instead ?

[takanome-dev]

Are you suggesting we use GitHub pages instead ?

No, we can totally keep using Nextjs and vercel

I had split the docs because I was failing to configure nextjs to share the repo alongside my code.

I see, have you considered setting up monorepo (using turborepo or nx)?
There is a bit of a learning curve but it's worth it. Pick one and read the docs. Try to set up a new monorepo project (private if you want) and play with it to understand how it works.

Then, you can try, in a private repo, creating a monorepo containing this repo and the docs (maybe also add an example folder where you can add a simple project that uses our package) and also try setting up the gh actions.

That's a lot 😅 You can skip the last paragraph and directly create a PR where you move this project to a monorepo. Of course, I'll be more than happy to help with that. Although I'm not an expert in setting up monorepos or anything else 😅 but we can all learn from each other and most importantly by making mistakes ✌️

[prjctimg]

Awesome 😎! Though I'm lost in the details 😂 the benefits of having it all under one roof are obvious.

I'd be grateful if you could help me up to speed on the basics of getting started with this migration.

We could perhaps clone the documentation repository inside of the project repository. The documentation site dould live inside a docs subdirectory whilst the rest of the codebase remains unchanged

I think that is the easiest and fastest approach. Unfortunately, I'm a bit restricted in terms of hardware at the moment (I'm on a dual core Celeron 😂) so I can't do resource intensive tasks like running the development server.

Most of my tasks at the moment are code editing and minimal testing with Jasmine and nodemon.

Could we open a separate issue for this so that it can be properly kept track of ?

Please feel free to proceed and make the necessary changes 👍 and let me know if there's any breaking changes like urls I'll have to be aware of so that we can work in parallel to keep track of each other's changes

[takanome-dev]

Sorry, totally missed that. Been busy these days, but I will try to put that on a PR by the end of the week

[prjctimg]

No worries! My network📡 is not at its peak either

In the meantime I've cloned the docs repo inside the project folder and trying to add support for GitHub Flavoured Markdown and p5js.

Committing recent changes

[takanome-dev]

Ahh man, I'm so sorry 😓 . Forgot this again. If someone is willing to give it a try, feel free to take it. Not sure when I'll be able to do this

[foss2cyber]

I would've taken this up, but I've been held up by some.....stuff. Will try to get back to this asap. @prjctimg @takanome-dev

[prjctimg]

Ahh man, I'm so sorry 😓 . Forgot this again. If someone is willing to give it a try, feel free to take it. Not sure when I'll be able to do this

No worries!

Currently working on a lot of changes and normalizing behaviour across conversions. This December I won't release anything until everything is stabilized.

You can always contribute at a more convenient time 👍

Happy holidays, devs!