SDK API reference (#733)

Refs: #699

Here we add the [`typedoc`](https://typedoc.org) tool in order to
generate a Markdown API reference from the TSDoc comments. The generated
API reference is stored in the `api-reference` directory of the SDK
module.

The API reference docs can be re-generated using:
```
yarn docs
```

The new CI job `typescript-docs` checks whether the API reference was
re-generated after source code changes. If there is a need to do that,
this job fails at the `Check docs up to date` step.

To facilitate work, a pre-commit hook `typescript-docs` was added. It
automatically runs `yarn docs` before each commit. If there are any
changes in the API reference, the pre-commit hook fails but the file
changes remain so it's enough to do Git commit again. To leverage the
new hook, it's enough to run this command in the `tbtc-v2` repository
root directory:
```
pre-commit install
```

By the way, we are also setting the `repository` section in the SDK
`package.json` (this was previously done by mistake in the `solidity`
directory).

.github/workflows/typescript.yml

@@ -177,3 +177,36 @@ jobs:
 
       - name: Check formatting
         run: yarn format
+
+  typescript-docs:
+    needs: typescript-detect-changes
+    if: |
+      github.event_name == 'push'
+        || needs.typescript-detect-changes.outputs.path-filter == 'true'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./typescript
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "18.x"
+          cache: "yarn"
+          cache-dependency-path: typescript/yarn.lock
+
+      - name: Configure git to don't use unauthenticated protocol
+        run: git config --global url."https://".insteadOf git://
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Build
+        run: yarn build
+
+      - name: Generate docs
+        run: yarn docs
+
+      - name: Check docs up to date
+        run: git diff --exit-code || exit 1

.pre-commit-config.yaml

@@ -41,3 +41,9 @@ repos:
         files: "^cross-chain/arbitrum/"
         language: script
         description: "Checks cross-chain/arbitrum directory code according to the formatting configuration"
+      - id: typescript-docs
+        name: "Generate typescript API reference docs"
+        entry: /usr/bin/env bash -c "cd typescript && yarn docs"
+        files: "^typescript/"
+        language: script
+        description: "Generates typescript API reference docs according to the typedoc configuration"

solidity/package.json

@@ -76,10 +76,5 @@
   },
   "engines": {
     "node": ">= 14.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/keep-network/tbtc-v2.git",
-    "directory": "typescript"
   }
 }

typescript/.eslintignore

@@ -1,3 +1,4 @@
 dist/
 node_modules/
 typechain/
+api-reference/

typescript/.prettierignore

@@ -1,3 +1,4 @@
 dist/
 external/
 typechain/
+api-reference/

typescript/README.md

@@ -20,6 +20,7 @@ trustless tokenized Bitcoin to their users.
   - [Build](#build)
   - [Test](#test)
   - [Format](#format)
+  - [Auto-generated API reference](#auto-generated-api-reference)
 - [Documentation](#documentation)
 
 ## Quickstart
@@ -134,6 +135,19 @@ To format code automatically, invoke:
 yarn format:fix
 ```
 
+### Auto-generated API reference
+
+There is an auto-generated API reference documentation that must be
+re-generated in case of modifications in the source code. This can be
+done automatically using a pre-commit hook or manually using:
+
+```bash
+yarn docs
+```
+
+Generated API reference in form of Markdown files is saved
+to the [`api-reference`](./api-reference) directory.
+
 ## Documentation
 
 This README provides just a basic guidance. Comprehensive documentation for