Documentation improvements - suggestion for GitBook

[gtsonevv]

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

[frol]

@gtsonevv I love the improved look, but the setup looks a bit complex to me. I must say that I got used to automated docs.rs service that just takes my Rust crate and makes the docs out of it with zero configuration. I believe that the improved look will contribute to the adoption and I hope that we will be able to flesh out the docs with more examples and relevant information / references. What would be the best way forward? Will the free plan work for us, or should I register a paid plan?

[frol]

Where is this token used?

[frol]

There is no GH_PAT secret. As I mentioned in DM, there is MY_GITHUB_TOKEN secret associated with my frol account, so not near:.

[frol]

@race-of-sloths score 5

[race-of-sloths]

@gtsonevv Thank you for your contribution! Your pull request is now a part of the Race of Sloths!
Weekly streak is on the road, smart strategy! Secure your streak with another PR!

Current status: executed

Reviewer	Score
@frol	5

Your contribution is much appreciated with a final score of 5!
You have received 50 Sloth points for this contribution

What is the Race of Sloths

Race of Sloths is a friendly competition where you can participate in challenges and compete with other open-source contributors within your normal workflow

For contributors:

• Tag @race-of-sloths inside your pull requests
• Wait for the maintainer to review and score your pull request
• Check out your position in the Leaderboard
• Keep weekly and monthly streaks to reach higher positions
• Boast your contributions with a dynamic picture of your Profile

For maintainers:

• Score pull requests that participate in the Race of Sloths
• Engage contributors with fair scoring and fast responses so they keep their streaks
• Promote the Race to the point where the Race starts promoting you
• Grow the community of your contributors

Feel free to check our website for additional details!

Bot commands

• For contributors
  • Include a PR: @race-of-sloths include to enter the Race with your PR
• For maintainers:
  • Invite contributor @race-of-sloths invite to invite the contributor to participate in a race or include it, if it's already a runner.
  • Assign points: @race-of-sloths score [1/2/3/5/8/13] to award points based on your assessment.
  • Reject this PR: @race-of-sloths exclude to send this PR back to the drawing board.
  • Exclude repo: @race-of-sloths pause to stop bot activity in this repo until @race-of-sloths unpause command is called