Add: Typedocs (#1208)

* feat: add typedoc + change tsconfig.base * feat: add typedoc action * feat: temporary disable release action * feat: update typedoc generator action * feat: update typedoc generator action to support pnpm * feat: update action logic for testing purposes * feat: configure pnpm back to version 7 * feat: update action configuration * feat: change action configuration * feat: update build documentation action * feat: minor changes * feat: update tsconfig.base.json * feat: update typedoc action * feat: add readme option * feat: update entryPoints * feat: update entryPoints * feat: change entryPoints to near-api-js * feat: add package entrypointstrategy * feat: fix adding modules content on typedoc generated documentation * feat: update tsconfig.base.json * feat: update tsconfig * feat: update tsconfig files for each package * feat: add custom-theme * feat: add custom-theme * feat: testing configuration * feat: add externalSymbolLinkMappings * feat: add typedoc-theme * feat: update readme files links * feat: update typedoc options * feat: update tsconfig * feat: update out folder * feat: update typedoc-generator * feat: add target-folder option to typedoc-generator action * feat: update typedoc docs generator to allow linking README files to packages files * feat: minor changes * feat: update typedoc action * feat: elete tsconfig.json * feat: make changes to the step Update gh-pages Branch * feat: update typedoc-generator steps * feat: update action * feat: add user/email * feat: add tsconfig.json.local * feat: add write permissions * feat: github action small change * feat: fix divergent changes on action * feat: small changes * feat: add action that syncs branches * feat: fix permission issues * feat: created generated-documentation folder * feat: add folder * feat: clean code * feat: change action configuration * feat: change out folder to build * feat: enable target-folder * feat: update build destination folder * feat: change action logic * feat: update action * feat: disable pull-request action * feat: clean docs folder * feat: remove lfs: true * feat: update action * feat: add concurrency handler * feat: remove clean option * feat: revert to gh-pages root * feat: enable pull-request.action * feat: add near-api-js package to docs job * feat: disable jekyll * feat: update links on README_TYPEDOC.md * feat: migrate typedoc.json to javascript to handle github full path * feat: delete typedoc.json * feat: fix @link on account.ts * feat: update near-api-js tsconfig * feat: tsconfig test for near-api-js * feat: add lib and text to exclude option * feat: remove @link tag on unresolved link RequestSignTransactionsOptions * feat: add typedoc-plugin-merge-modules * feat: update tsconfig.base * feat: update pnpm-lock * feat: delete tsconfig.json * feat: remove plugin typedoc-plugin-merge-modules * feat: disable old docs-generator action * feat: update near-api-js tsconfig * feat: updtae tsconfig.base * feat: update action * feat: update action * feat: fix failed to resolve link warning * feat: fix not included in the documentation warning * feat: delete typedoc.json file * feat: typedoc update * feat: test @link tag * feat: @link wip * feat: @link change * feat: fix @link near.ts * feat: near.ts @link * feat: change near.ts * feat: update @link * feat: update @link tag * feat: readme.md file update * feat: enable release action * feat: update githubpages option * refactor: update typedoc-generator * fix: fixed all links in docs * fix: updated action * fix: docs * feat: added near-api-js to typedocs * fix: output dir for typedocs * fix: non-overlapping name for action --------- Co-authored-by: few-sw <[email protected]>
near · Nov 30, 2023 · 6e5e41e · 6e5e41e
1 parent 0be6c42
commit 6e5e41e
Show file tree

Hide file tree

Showing 51 changed files with 451 additions and 218 deletions.
diff --git a/.github/workflows/docs-generator-trigger.yml b/.github/workflows/docs-generator-trigger.yml
diff --git a/.github/workflows/typedoc-generator.yml b/.github/workflows/typedoc-generator.yml
@@ -0,0 +1,46 @@
+name: Deploy TypeDoc on GitHub pages
+
+on:
+    push:
+      branches:
+        master  
+
+env:
+  NODE_VERSION: 18.x
+  ENTRY_FILE: 'packages'
+  CONFIG_PATH: 'tsconfig.base.json'
+  USES_PNPM: 'true'
+  DESTINATION_FOLDER: "docs"
+
+jobs:
+  deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Setup pnpm
+        uses: pnpm/[email protected]
+        with:
+          version: 7
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build project
+        run:  pnpm build
+
+      - name: Build documentation
+        run:  pnpm docs:generate
+
+      - name: Deploy to GitHub pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: ${{ env.DESTINATION_FOLDER }}
+          clean: true
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,5 @@ lib/
 test-keys/
 
 .turbo
+
+typedoc-docs/
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # NEAR JavaScript API
 
-[![Build Status](https://travis-ci.com/near/near-api-js.svg?branch=master)](https://travis-ci.com/near/near-api-js)
+[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fnear%2Fnear-api-js%2Fbadge&style=flat&label=Build)](https://actions-badge.atrox.dev/near/near-api-js/goto)
 [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/near/near-api-js) 
 
 NEAR JavaScript API is a complete library to interact with the NEAR blockchain. You can use it in the browser, or in Node.js runtime.

diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/README_TYPEDOC.md b/docs/README_TYPEDOC.md
diff --git a/package.json b/package.json
@@ -14,7 +14,8 @@
     "autoclave": "rimraf packages/**/dist && rimraf packages/**/lib && rimraf packages/**/node_modules && rimraf packages/**/coverage && rimraf packages/**/.turbo && rm -rf node_modules",
     "test": "turbo run test",
     "release": "changeset publish",
-    "prepare": "husky install"
+    "prepare": "husky install",
+    "docs:generate": "typedoc"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.4.6",
@@ -28,6 +29,7 @@
     "husky": "^7.0.4",
     "rimraf": "^3.0.2",
     "turbo": "^1.4.5",
+    "typedoc": "^0.25.3",
     "typescript": "^4.9.4"
   }
 }
diff --git a/packages/accounts/README.md b/packages/accounts/README.md
@@ -4,14 +4,14 @@ A collection of classes, functions, and types for interacting with accounts and
 
 ## Modules
 
-- [Account](src/account.ts) a class with methods to transfer NEAR, manage account keys, sign transactions, etc.
-- [AccountMultisig](src/account_multisig.ts) a [multisig](https://github.com/near/core-contracts/tree/master/multisig) deployed `Account` requiring multiple keys to sign transactions
-- [Account2FA](src/account_2fa.ts) extension of `AccountMultisig` used in conjunction with 2FA provided by [near-contract-helper](https://github.com/near/near-contract-helper)
-- [AccountCreator](src/account_creator.ts) classes for creating NEAR accounts
-- [Contract](src/contract.ts) represents a deployed smart contract with view and/or change methods
-- [Connection](src/connection.ts) a record containing the information required to connect to NEAR RPC
-- [Constants](src/constants.ts) account-specific constants
-- [Types](src/types.ts) account-specific types
+- [Account](https://github.com/near/near-api-js/blob/master/packages/accounts/src/account.ts) a class with methods to transfer NEAR, manage account keys, sign transactions, etc.
+- [AccountMultisig](https://github.com/near/near-api-js/blob/master/packages/accounts/src/account_multisig.ts) a [multisig](https://github.com/near/core-contracts/tree/master/multisig) deployed `Account` requiring multiple keys to sign transactions
+- [Account2FA](https://github.com/near/near-api-js/blob/master/packages/accounts/src/account_2fa.ts) extension of `AccountMultisig` used in conjunction with 2FA provided by [near-contract-helper](https://github.com/near/near-contract-helper)
+- [AccountCreator](https://github.com/near/near-api-js/blob/master/packages/accounts/src/account_creator.ts) classes for creating NEAR accounts
+- [Contract](https://github.com/near/near-api-js/blob/master/packages/accounts/src/contract.ts) represents a deployed smart contract with view and/or change methods
+- [Connection](https://github.com/near/near-api-js/blob/master/packages/accounts/src/connection.ts) a record containing the information required to connect to NEAR RPC
+- [Constants](https://github.com/near/near-api-js/blob/master/packages/accounts/src/constants.ts) account-specific constants
+- [Types](https://github.com/near/near-api-js/blob/master/packages/accounts/src/types.ts) account-specific types
 
 # License
 

diff --git a/packages/accounts/src/account.ts b/packages/accounts/src/account.ts
@@ -81,20 +81,20 @@ export interface SignAndSendTransactionOptions {
     actions: Action[];
     /**
      * Metadata to send the NEAR Wallet if using it to sign transactions.
-     * @see {@link RequestSignTransactionsOptions}
+     * @see RequestSignTransactionsOptions
      */
     walletMeta?: string;
     /**
      * Callback url to send the NEAR Wallet if using it to sign transactions.
-     * @see {@link RequestSignTransactionsOptions}
+     * @see RequestSignTransactionsOptions
      */
     walletCallbackUrl?: string;
     returnError?: boolean;
 }
 
 /**
  * Options used to initiate a function call (especially a change function call)
- * @see {@link account!Account#viewFunction} to initiate a view function call
+ * @see {@link Account#viewFunction | viewFunction} to initiate a view function call
  */
 export interface FunctionCallOptions {
     /** The NEAR account id where the contract is deployed */
@@ -122,18 +122,18 @@ export interface FunctionCallOptions {
 export interface ChangeFunctionCallOptions extends FunctionCallOptions {
     /**
      * Metadata to send the NEAR Wallet if using it to sign transactions.
-     * @see {@link RequestSignTransactionsOptions}
+     * @see RequestSignTransactionsOptions
     */
     walletMeta?: string;
     /**
      * Callback url to send the NEAR Wallet if using it to sign transactions.
-     * @see {@link RequestSignTransactionsOptions}
+     * @see RequestSignTransactionsOptions
     */
     walletCallbackUrl?: string;
 }
-export interface ViewFunctionCallOptions extends FunctionCallOptions { 
-    parse?: (response: Uint8Array) => any; 
-    blockQuery?: BlockReference; 
+export interface ViewFunctionCallOptions extends FunctionCallOptions {
+    parse?: (response: Uint8Array) => any;
+    blockQuery?: BlockReference;
 }
 
 interface StakedBalance {
@@ -163,11 +163,7 @@ function bytesJsonStringify(input: any): Buffer {
 }
 
 /**
- * This class provides common account related RPC calls including signing transactions with a {@link utils/key_pair!KeyPair}.
- *
- * @hint Use {@link walletAccount!WalletConnection} in the browser to redirect to [NEAR Wallet](https://wallet.near.org/) for Account/key management using the {@link key_stores/browser_local_storage_key_store!BrowserLocalStorageKeyStore}.
- * @see [https://docs.near.org/docs/develop/front-end/naj-quick-reference#account](https://docs.near.org/tools/near-api-js/quick-reference#account)
- * @see [Account Spec](https://nomicon.io/DataStructures/Account.html)
+ * This class provides common account related RPC calls including signing transactions with a {@link "@near-js/crypto".key_pair.KeyPair | KeyPair}.
  */
 export class Account {
     readonly connection: Connection;
@@ -194,7 +190,7 @@ export class Account {
      * Create a signed transaction which can be broadcast to the network
      * @param receiverId NEAR account receiving the transaction
      * @param actions list of actions to perform as part of the transaction
-     * @see {@link providers/json-rpc-provider!JsonRpcProvider#sendTransaction | JsonRpcProvider.sendTransaction}
+     * @see {@link "@near-js/providers".json-rpc-provider.JsonRpcProvider.sendTransaction | JsonRpcProvider.sendTransaction}
      */
     protected async signTransaction(receiverId: string, actions: Action[]): Promise<[Uint8Array, SignedTransaction]> {
         const accessKeyInfo = await this.findAccessKey(receiverId, actions);
@@ -214,7 +210,7 @@ export class Account {
 
     /**
      * Sign a transaction to preform a list of actions and broadcast it using the RPC API.
-     * @see {@link providers/json-rpc-provider!JsonRpcProvider#sendTransaction | JsonRpcProvider.sendTransaction}
+     * @see {@link "@near-js/providers".json-rpc-provider.JsonRpcProvider | JsonRpcProvider }
      */
     async signAndSendTransaction({ receiverId, actions, returnError }: SignAndSendTransactionOptions): Promise<FinalExecutionOutcome> {
         let txHash, signedTx;
@@ -248,7 +244,7 @@ export class Account {
         printTxOutcomeLogsAndFailures({ contractId: signedTx.transaction.receiverId, outcome: result });
 
         // Should be falsy if result.status.Failure is null
-        if (!returnError && typeof result.status === 'object' && typeof result.status.Failure === 'object'  && result.status.Failure !== null) {
+        if (!returnError && typeof result.status === 'object' && typeof result.status.Failure === 'object' && result.status.Failure !== null) {
             // if error data has error_message and error_type properties, we consider that node returned an error in the old format
             if (result.status.Failure.error_message && result.status.Failure.error_type) {
                 throw new TypedError(
@@ -266,7 +262,7 @@ export class Account {
     accessKeyByPublicKeyCache: { [key: string]: AccessKeyView } = {};
 
     /**
-     * Finds the {@link providers/provider!AccessKeyView} associated with the accounts {@link utils/key_pair!PublicKey} stored in the {@link key_stores/keystore!KeyStore}.
+     * Finds the {@link AccessKeyView} associated with the accounts {@link PublicKey} stored in the {@link "@near-js/keystores".keystore.KeyStore | Keystore}.
      *
      * @todo Find matching access key based on transaction (i.e. receiverId and actions)
      *
@@ -396,16 +392,16 @@ export class Account {
         this.validateArgs(args);
         let functionCallArgs;
 
-        if(jsContract){
-            const encodedArgs = this.encodeJSContractArgs( contractId, methodName, JSON.stringify(args) );
-            functionCallArgs =  ['call_js_contract', encodedArgs, gas, attachedDeposit, null, true ];
-        } else{
+        if (jsContract) {
+            const encodedArgs = this.encodeJSContractArgs(contractId, methodName, JSON.stringify(args));
+            functionCallArgs = ['call_js_contract', encodedArgs, gas, attachedDeposit, null, true];
+        } else {
             const stringifyArg = stringify === undefined ? stringifyJsonOrBytes : stringify;
             functionCallArgs = [methodName, args, gas, attachedDeposit, stringifyArg, false];
         }
 
         return this.signAndSendTransaction({
-            receiverId: jsContract ? this.connection.jsvmAccountId: contractId,
+            receiverId: jsContract ? this.connection.jsvmAccountId : contractId,
             // eslint-disable-next-line prefer-spread
             actions: [functionCall.apply(void 0, functionCallArgs)],
             walletMeta,
@@ -543,20 +539,20 @@ export class Account {
         blockQuery = { finality: 'optimistic' }
     }: ViewFunctionCallOptions): Promise<any> {
         let encodedArgs;
-        
+
         this.validateArgs(args);
-    
-        if(jsContract){
-            encodedArgs = this.encodeJSContractArgs(contractId, methodName, Object.keys(args).length >  0 ? JSON.stringify(args): '');
-        } else{
-            encodedArgs =  stringify(args);
+
+        if (jsContract) {
+            encodedArgs = this.encodeJSContractArgs(contractId, methodName, Object.keys(args).length > 0 ? JSON.stringify(args) : '');
+        } else {
+            encodedArgs = stringify(args);
         }
 
         const result = await this.connection.provider.query<CodeResult>({
             request_type: 'call_function',
             ...blockQuery,
             account_id: jsContract ? this.connection.jsvmAccountId : contractId,
-            method_name: jsContract ? 'view_js_contract'  : methodName,
+            method_name: jsContract ? 'view_js_contract' : methodName,
             args_base64: encodedArgs.toString('base64')
         });
 
@@ -575,7 +571,7 @@ export class Account {
      * @param prefix allows to filter which keys should be returned. Empty prefix means all keys. String prefix is utf-8 encoded.
      * @param blockQuery specifies which block to query state at. By default returns last "optimistic" block (i.e. not necessarily finalized).
      */
-    async viewState(prefix: string | Uint8Array, blockQuery: BlockReference = { finality: 'optimistic' } ): Promise<Array<{ key: Buffer; value: Buffer}>> {
+    async viewState(prefix: string | Uint8Array, blockQuery: BlockReference = { finality: 'optimistic' }): Promise<Array<{ key: Buffer; value: Buffer }>> {
         const { values } = await this.connection.provider.query<ViewStateResult>({
             request_type: 'view_state',
             ...blockQuery,
@@ -651,12 +647,12 @@ export class Account {
      * NOTE: If the tokens are delegated to a staking pool that is currently on pause or does not have enough tokens to participate in validation, they won't be accounted for.
      * @returns {Promise<ActiveDelegatedStakeBalance>}
      */
-    async getActiveDelegatedStakeBalance(): Promise<ActiveDelegatedStakeBalance>  {
+    async getActiveDelegatedStakeBalance(): Promise<ActiveDelegatedStakeBalance> {
         const block = await this.connection.provider.block({ finality: 'final' });
         const blockHash = block.header.hash;
         const epochId = block.header.epoch_id;
         const { current_validators, next_validators, current_proposals } = await this.connection.provider.validators(epochId);
-        const pools:Set<string> = new Set();
+        const pools: Set<string> = new Set();
         [...current_validators, ...next_validators, ...current_proposals]
             .forEach((validator) => pools.add(validator.account_id));
 
@@ -704,7 +700,7 @@ export class Account {
             }
             return result;
         },
-        { stakedValidators: [], failedValidators: [], total: new BN(0) });
+            { stakedValidators: [], failedValidators: [], total: new BN(0) });
 
         return {
             ...summary,

diff --git a/packages/accounts/src/account_2fa.ts b/packages/accounts/src/account_2fa.ts
@@ -46,7 +46,7 @@ export class Account2FA extends AccountMultisig {
 
     /**
      * Sign a transaction to preform a list of actions and broadcast it using the RPC API.
-     * @see {@link providers/json-rpc-provider!JsonRpcProvider#sendTransaction | JsonRpcProvider.sendTransaction}
+     * @see {@link "@near-js/providers".json-rpc-provider.JsonRpcProvider.sendTransaction | JsonRpcProvider.sendTransaction}
      */
     async signAndSendTransaction({ receiverId, actions }: SignAndSendTransactionOptions): Promise<FinalExecutionOutcome> {
         await super.signAndSendTransaction({ receiverId, actions });

diff --git a/packages/accounts/src/contract.ts b/packages/accounts/src/contract.ts
@@ -85,14 +85,14 @@ export interface ContractMethods {
     /**
      * Methods that change state. These methods cost gas and require a signed transaction.
      *
-     * @see {@link account!Account.functionCall}
+     * @see {@link Account#functionCall}
      */
     changeMethods: string[];
 
     /**
      * View methods do not require a signed transaction.
      *
-     * @see {@link account!Account#viewFunction}
+     * @see {@link Account#viewFunction}
      */
     viewMethods: string[];