Merge pull request #7 from few-sw/typedoc-configuration

Typedoc configuration

.github/workflows/typedoc-generator.yml

@@ -3,37 +3,58 @@ name: Deploy TypeDoc on GitHub pages
 on:
     push:
       branches:
-        - master  
+        master  
 
 env:
   NODE_VERSION: 18.x
-  ENTRY_FILE: 'src'
-  CONFIG_PATH: './tsconfig.base.json'
-
+  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/action-setup@v2.2.2
+        with:
+          version: 7
+
       - name: Install dependencies
-        run: npm install
+        run: pnpm install
+
       - name: Build documentation
-        uses: few-sw/typedoc-action@v2.6.2
+        uses: few-sw/typedoc-action@v2.6.2 
         with:
           entry: ${{ env.ENTRY_FILE }}
           config:  ${{ env.CONFIG_PATH }}
+          pnpm: ${{ env.USES_PNPM }}
+
+      # - name: Sync branch
+      #   id: pull
+      #   uses: tretuna/sync-branches@1.2.0
+      #   with:
+      #     GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+      #     FROM_BRANCH: 'typedoc-configuration'
+      #     TO_BRANCH: 'gh-pages'
+
       - name: Deploy to GitHub pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: gh-pages
-          folder: docs
+          folder: ${{ env.DESTINATION_FOLDER }}
           clean: true
-      # - name: Deploy
-      #   uses: peaceiris/actions-gh-pages@v3
-      #   with:
-      #     github_token: ${{ secrets.GITHUB_TOKEN }}
-      #     publish_dir: ./docs 
+          # target-folder: ${{ env.DESTINATION_FOLDER }}
+          # clean-exclude: |
+          #   docs/package-architecture.png
+          #   docs/README_TYPEDOC.md
+          #   docs/README.md

.gitignore

@@ -23,3 +23,5 @@ lib/
 test-keys/
 
 .turbo
+
+typedoc-docs/

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": "typedoc --tsconfig tsconfig.local-test.json"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.4.6",
@@ -28,7 +29,7 @@
     "husky": "^7.0.4",
     "rimraf": "^3.0.2",
     "turbo": "^1.4.5",
-    "typescript": "^4.9.4",
-    "typedoc": "^0.25.3"
+    "typedoc": "^0.25.3",
+    "typescript": "^4.9.4"
   }
 }

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
 

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,12 +122,12 @@ 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;
 }
@@ -163,9 +163,9 @@ function bytesJsonStringify(input: any): Buffer {
 }
 
 /**
- * This class provides common account related RPC calls including signing transactions with a {@link utils/key_pair!KeyPair}.
+ * This class provides common account related RPC calls including signing transactions with a {@link 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}.
+ * @hint Use {@link WalletConnection} in the browser to redirect to [NEAR Wallet](https://wallet.near.org/) for Account/key management using the {@link 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)
  */
@@ -194,7 +194,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 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 +214,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 providers/json-rpc-provider!JsonRpcProvider_sendTransaction | JsonRpcProvider.sendTransaction}
      */
     async signAndSendTransaction({ receiverId, actions, returnError }: SignAndSendTransactionOptions): Promise<FinalExecutionOutcome> {
         let txHash, signedTx;
@@ -266,7 +266,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 key_stores/keystore!KeyStore}.
      *
      * @todo Find matching access key based on transaction (i.e. receiverId and actions)
      *

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 providers/json-rpc-provider!JsonRpcProvider_sendTransaction | JsonRpcProvider.sendTransaction}
      */
     async signAndSendTransaction({ receiverId, actions }: SignAndSendTransactionOptions): Promise<FinalExecutionOutcome> {
         await super.signAndSendTransaction({ receiverId, actions });

packages/accounts/src/contract.ts

@@ -84,14 +84,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[];
 

packages/accounts/tsconfig.json

@@ -4,6 +4,18 @@
         "preserveSymlinks": false,
         "outDir": "./lib",
     },
+    "typedocOptions": {
+        "skipErrorChecking": true,
+        "entryPoints": ["src"],
+        "entryPointStrategy": "expand",
+        "out": "docs",
+        "exclude": ["node_modules","test","lib"],
+        "githubPages": true,
+        "emit": "both",
+        "validation": {
+            "notExported": false
+        }
+    },
     "files": [
         "src/index.ts"
     ]

packages/biometric-ed25519/tsconfig.json

@@ -2,6 +2,18 @@
     "extends": "../../tsconfig.browser.json",
     "compilerOptions": {
         "outDir": "./lib",
+    }, 
+    "typedocOptions": {
+        "skipErrorChecking": true,
+        "entryPoints": ["src"],
+        "entryPointStrategy": "expand",
+        "out": "docs",
+        "exclude": ["node_modules","test","lib"],
+        "githubPages": true,
+        "emit": "both",
+        "validation": {
+            "notExported": false
+        }
     },
     "files": [
         "src/index.ts",

packages/cookbook/tsconfig.json

@@ -0,0 +1,31 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "allowJs": true,
+        "outDir": "./dist",
+      },
+    "typedocOptions": {
+        "skipErrorChecking": true,
+        "entryPoints": [
+            "accounts",
+            "api-keys",
+            "transactions",
+            "utils"
+        ],
+        "entryPointStrategy": "expand",
+        "out": "docs",
+        "exclude": [
+            "node_modules"
+        ],
+        "excludeNotDocumented": true,
+        "excludeNotDocumentedKinds": [
+            "Module",
+            "Reference"
+        ],
+        "githubPages": true,
+    },
+    "include": [
+        "**/*.js",
+        "**/*.ts"
+    ]
+}

packages/crypto/README.md

@@ -4,11 +4,11 @@ A collection of classes and types for working with cryptographic key pairs.
 
 ## Modules
 
-- [PublicKey](src/public_key.ts) representation of a public key capable of verifying signatures
-- [KeyPairBase](src/key_pair_base.ts) abstract class representing a key pair
-- [KeyPair](src/key_pair.ts) abstract extension of `KeyPairBase` with static methods for parsing and generating key pairs
-- [KeyPairEd25519](src/key_pair_ed25519.ts) implementation of `KeyPairBase` using [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519)
-- [Constants](src/constants.ts) keypair-specific constants
+- [PublicKey](https://github.com/near/near-api-js/blob/master/packages/crypto/src/public_key.ts) representation of a public key capable of verifying signatures
+- [KeyPairBase](https://github.com/near/near-api-js/blob/master/packages/crypto/src/key_pair_base.ts) abstract class representing a key pair
+- [KeyPair](https://github.com/near/near-api-js/blob/master/packages/crypto/src/key_pair.ts) abstract extension of `KeyPairBase` with static methods for parsing and generating key pairs
+- [KeyPairEd25519](https://github.com/near/near-api-js/blob/master/packages/crypto/src/key_pair_ed25519.ts) implementation of `KeyPairBase` using [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519)
+- [Constants](https://github.com/near/near-api-js/blob/master/packages/crypto/src/constants.ts) keypair-specific constants
 
 # License
 

packages/crypto/tsconfig.json

@@ -3,7 +3,19 @@
     "compilerOptions": {
         "outDir": "./lib",
     },
+    "typedocOptions": {
+        "skipErrorChecking": true,
+        "entryPoints": ["src"],
+        "entryPointStrategy": "expand",
+        "out": "docs",
+        "exclude": ["node_modules","test","lib"],
+        "githubPages": true,
+        "emit": "both",
+        "validation": {
+            "notExported": false
+        }
+    },
     "files": [
         "src/index.ts"
     ]
-}
+}

packages/iframe-rpc/tsconfig.json

@@ -3,6 +3,17 @@
     "compilerOptions": {
         "outDir": "./lib",
     },
+    "typedocOptions": {
+        "skipErrorChecking": true,
+        "entryPoints": ["src"],
+        "entryPointStrategy": "expand",
+        "out": "docs",
+        "exclude": ["node_modules","test","lib"],
+        "githubPages": true,
+        "validation": {
+            "notExported": false
+        }
+    },
     "files": [
         "src/index.ts"
     ]