We now have a npm run docs command that will basically create docs directory from the src directory.

The output is HTML files.

Because these are generated HTML docs, these make more sense as part of the build-deployment process rather than source documentation.

The idea is to create a build stage job called docs.

docs:
  stage: build
  script:
    - nix-shell --packages nodejs --run "npm install"
    - nix-shell --packages nodejs --run "npm run docs"
  only:
    - master

This runs concurrently build the build of the packages it only runs on the master. So only when master builds do we end up creating the docs.

However we just end up producing a special directory. That directory should then be deployed to gh-pages.

The idea is to do this:

typedoc --mode modules --out /tmp/docs src
git checkout --orphan gh-pages

This creates a new branch with no history.

I then delete everything in the current directory except .git.

Then I move back mv /tmp/docs/* ..

After gh-pages is created you can just switch with git checkout gh-pages.

But remember ignored stuff might be left there.

Also removed the typdocs.js. It's not needed.

One problem is when mv or cp -R it may not remove useless files. So docs files that no longer exists. So it makes sense to remove the contents of the directory before copying again.

find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -r '{}' \;

That will remove everything in the current directory except .git.

Then we can move back the docs into it.

Ok so then the idea is that the CI/CD needs to produce /tmp/docs.

Then we need to use gitAndTools.gh to initiate a PR... or even just directly push to gh-pages.

It's probably better to just send a PR for now.

The docs are being hosted here: https://matrixai.github.io/TypeScript-Demo-Lib/

So the idea is to use:

typedoc --out /tmp/docs src
git checkout gh-pages
find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -r '{}' \;
mv /tmp/docs/* .
git add -A
git commit -m 'Updated Docs'
gh pr create --base 'gh-pages' --fill

Note that if the user has access. The gh pr create command just pushes it up. No PR created at all.

Interactive authentication gh tokens is in the ~/.config/gh/config.yaml. Which looks like:

hosts:
    github.com:
        oauth_token: ...
        user: CMCDragonkai

There is GITHUB_TOKEN=... gh pr checkout 3 from cli/cli#976

However that appears to be on a later version of gitAndTools.gh. The one we have in our overlay seems to be earlier.

[nix-shell:~/Projects]$ gh --version
gh version 0.9.0 (1970-01-01)
https://github.com/cli/cli/releases/tag/v0.9.0

Updating to 42674051d12540d4a996504990c6ea3619505953 leads to being able to use GITHUB_TOKEN=... gh ....

So now we can attempt to create a PR.

So this ends up failing:

gh pr create --base 'gh-pages'

Because it says:

must be on a branch named differently than "gh-pages"

I think gh thinks it is wrong to create a PR to the gh-pages from gh-pages since you are already on the same branch.

I guess if you are going to do this. You should already be in a different git repo or git branch with shared history to the branch. So it make sense if the bot clones this repo and does it.

Might not work from my own repo.

Time to try it.

Another issue is that git commit -am will require some information about who the user is when they commit. So we will say that the bot has created this commit. MatrixAIBot.

But what is the git user is MatrixAI-Bot. But we haven't constructed this user yet.

I believe this is done in ~/.gitconfig under:

[user]
    name = MatrixAI-Bot
    email = [email protected]

We can also do:

git commit --author="Name <email>" -m "whatever"

Or:

GIT_AUTHOR_NAME
GIT_AUTHOR_EMAIL

Only the name is actually required. The email is optional.

The GITHUB_TOKEN has been created for MatrixAI-Bot. Which is me!

And then added to Gitlab OS group.

As well as the above additional environment variables.

So going to try to merge this and see what happens since it has to take place inside Gitlab.

So by changing pkgs.nix to be:

import (
  let rev = "42674051d12540d4a996504990c6ea3619505953"; in
  fetchTarball "https://github.com/NixOS/nixpkgs-channels/archive/${rev}.tar.gz"
)

This allows us to do:

nix-shell -I nixpkgs=./pkgs.nix --packages gitAndTools.gh --run 'gh pr create --base "gh-pages" --fill'

Thus allowing us to bring in packages while pinning to specific commit revisions in the pkgs.nix instead of just the overlay.