Documentation improvements - suggestion for GitBook

[dim-daskalov]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• Commit messages follow the conventional commits spec
• If this is a code change: I have written unit tests.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Test Plan

Related issues/PRs

GitBook

GitBook might be a good alternative that can be used to update the visuals of the documentation.

There is a free version, but for it we have some limitations.

Only one user can be supported in the free version, for every additional user included, there is a price. More information can be found in here - https://www.gitbook.com/pricing

The Plus plan might be enough for what we are after, and depending on monthly or annual plan, the costs might be decent.

After my research, I conducted that currently there is a limit on the documentation import size -
The maximum number of pages that can be uploaded in a single import is 20.

There is a solution for that, with no limitations - https://docs.gitbook.com/integrations/git-sync

Also there is some other limitations, more info can be found here - https://docs.gitbook.com/help-and-faq/faq/content-creation-faq

If we decide to use GitBook, I have included a new script file generate-docs-markdown.js, and a new script trigger command docs:generate-markdown in package.json

Regarding the automation of the deployment of the documentation, GitHub workflow file can be added.

Below you can find an example file for the automation process.

Example:
typedoc-generate-gitbook-docs.yml

name: Deploy TypeDoc to GitBook

on:
  push:
    branches:
      - YOUR_TRIGGER_BRANCH
  
env:
  NODE_VERSION: 18.x
  ENTRY_FILE: "packages"
  CONFIG_PATH: "tsconfig.base.json"
  USES_PNPM: "true"
  
jobs:
  deploy:
    concurrency: ci-${{ github.ref }}
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '[skip ci]')"
    permissions:
      contents: write
    steps:
     - uses: actions/checkout@v4
  
     - uses: actions/setup-node@v3
        with:
          node-version: ${{ env.NODE_VERSION }}
  
     - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 7
  
     - name: Install dependencies
        run: pnpm install --no-frozen-lockfile
  
     - name: Build project
        run: pnpm build
  
     - name: Build documentation
        run: pnpm docs:generate-markdown
  
     - name: Deploy to GitBook
        env:
            # GITBOOK_TOKEN, more information can be found in here - https://developer.gitbook.com/gitbook-api/authentication
          GITBOOK_TOKEN: ${{ secrets.YOUR_GITBOOK_TOKEN }}
            # GITHUB_PERSONAL_ACCESS_TOKEN more information can be found in here - https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
          GH_PAT: ${{ secrets.YOUR_GITHUB_PERSONAL_ACCESS_TOKEN }}
        run: |
          git clone --branch=YOUR_DOCUMENTATION_BRANCH https://YOUR_GITBOOK_REPOSITORY.git book
          rsync -av --delete markdown-docs/ book/markdown-docs/
          cd book
          git config user.name "GitHub Actions"
          git config user.email "[email protected]"
          git add markdown-docs/
          git commit -m "Update documentation [skip ci]"
          git push https://YOUR_GITBOOK_REPOSITORY.git YOUR_DOCUMENTATION_BRANCH

Notes:

We could use this library - https://github.com/ZanderZhao/gitbook-action for the last part Deploy to GitBook, but something to take in mind is that it will replace the old documentation content in gh-pages branch. https://github.com/ZanderZhao/gitbook-action?tab=readme-ov-file#step3-choose-options

• Replace YOUR_GITBOOK_REPOSITORY with the actual GitBook repository URL.
• The YOUR_GITBOOK_TOKEN secret should be added to your GitHub repository settings. This token allows the GitHub Actions workflow to push changes to your GitBook repository.
• YOUR_DOCUMENTATION_BRANCH should be the branch which will be connected to the GitBook - GitHub Sync
• YOUR_TRIGGER_BRANCH should be the branch from which the GitHub Workflow will be triggered.
• YOUR_GITHUB_PERSONAL_ACCESS_TOKEN secret should be added to your GitHub repository settings. This token allows the GitHub Actions workflow to push changes to the GitHub repository.

This setup will automatically build and deploy TypeDoc documentation to GitBook whenever there is a push to the suggested branch.

The end documentation can look something like this: - https://limechain.gitbook.io/limechain-test