From 8918814256a959de6b7a0c13a85eb42ed8055a1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Bruus=20Zeppelin?= Date: Mon, 2 Oct 2023 15:05:51 +0200 Subject: [PATCH] Adapt documentation --- .eslintrc.cjs | 5 +- docs/pages/documentation.md | 13 ++--- docs/pages/misc-pages/grpc-v1.md | 2 +- docs/pages/misc-pages/upgrade-guide.md | 46 ++------------- docs/tsconfig.json | 3 +- docs/typedoc.config.cjs | 79 ++++++++++++++++++++++++++ docs/typedoc.json | 73 ------------------------ 7 files changed, 94 insertions(+), 127 deletions(-) create mode 100644 docs/typedoc.config.cjs delete mode 100644 docs/typedoc.json diff --git a/.eslintrc.cjs b/.eslintrc.cjs index ac50c26d7..a098a85a6 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -16,9 +16,8 @@ module.exports = { tsconfigRootDir: __dirname, project: [ './packages/**/tsconfig.json', - './packages/**/tsconfig.eslint.json', - './tsconfig.eslint.json', - './examples/tsconfig.eslint.json', + './docs/**/tsconfig.json', + '**/tsconfig.eslint.json', ], }, plugins: ['@typescript-eslint', 'import'], diff --git a/docs/pages/documentation.md b/docs/pages/documentation.md index 3b08cb349..568f535b6 100644 --- a/docs/pages/documentation.md +++ b/docs/pages/documentation.md @@ -11,13 +11,12 @@ utility functions}. A good way to get started is to check out the {@page runnable-examples.md runnable examples}. -To create a GRPC-Client in NodeJS-SDK: +To create a GRPC-Client for use with nodeJS: ```ts - import { credentials } from '@grpc/grpc-js/'; - import { createConcordiumClient } from '@concordium/node-sdk'; + import { ConcordiumGRPCNodeClient, credentials } from '@concordium/web-sdk/nodejs'; ... - return createConcordiumClient( + return new ConcordiumGRPCNodeClient( address, port, credentials.createSsl(), @@ -25,12 +24,12 @@ To create a GRPC-Client in NodeJS-SDK: ); ``` -To create a GRPC-Client in the Web-SDK: +To create a GRPC-Client for use in a browser (requires GRPC-web enabled on the node): ```ts - import { createConcordiumClient } from '@concordium/web-sdk'; + import { ConcordiumGRPCWebClient } from '@concordium/web-sdk'; ... - return createConcordiumClient( + return new ConcordiumGRPCWebClient( address, port, { timeout: 15000 } diff --git a/docs/pages/misc-pages/grpc-v1.md b/docs/pages/misc-pages/grpc-v1.md index fde400114..c7f30ddce 100644 --- a/docs/pages/misc-pages/grpc-v1.md +++ b/docs/pages/misc-pages/grpc-v1.md @@ -47,7 +47,7 @@ interface as the grpc v1 node client: - [getModuleSource](#getmodulesource) -## GRPCv1-Client +## GRPCv1-Client (only accessible prior to version 10) The ConcordiumNodeClient defines the interface to be used to send and receive data from a concordium-node. diff --git a/docs/pages/misc-pages/upgrade-guide.md b/docs/pages/misc-pages/upgrade-guide.md index 1d64a0658..ad4adddf9 100644 --- a/docs/pages/misc-pages/upgrade-guide.md +++ b/docs/pages/misc-pages/upgrade-guide.md @@ -1,6 +1,4 @@ -## Common SDK version 10 (Web 7) (Node 10) - -### Common +## SDK version 10 Several types have been replaced with a module containing the type itself together with functions for constructing and converting the type: @@ -48,12 +46,9 @@ The API now uses dedicated types instead of language primitives: - Uses `Duration` instead of a bigint. Can be constructed using `Duration.fromMillis()`. -### Web - The `@concordium/web-sdk` now requires bundlers to respect `exports` field of `package.json` of a module. This is due to relying on entrypoints declared in -the `exports` field of `@concordium/common-sdk` -and correspondingly `@concordium/rust-bindings` to make it possible to select +the `exports` field of `@concordium/rust-bindings` to make it possible to select only parts of the SDK to include in your application. Furthermore, the SDK is now published as an ES module, making it possible to eliminate dead code. @@ -96,12 +91,9 @@ with web3-id proofs. ### NodeJS -The `@concordium/node-sdk` module is no longer compatible with +The `@concordium/web-sdk` module is not compatible with node versions <16 and is published only as an ES module. -This is due to relying on entrypoints declared in the `exports` field -of `@concordium/common-sdk` and correspondingly `@concordium/rust-bindings` -to make it possible to select only parts of the SDK to include in your -application. +This, in turn, requires users to also run applications as ES modules. The easiest way to run your node application as an ES module, is by setting the `type` field of `package.json` to be set to `"module"`: @@ -121,36 +113,6 @@ For **TypeScript** users, at least typescript version 4.7 is required along with the setting `compilerOptions.moduleResultion` to `"node16"` or `"nodenext"` to match the resolution strategy of node version 16 and later. -The following entrypoints are made available for consumers of -`@concordium/node-sdk`: - -- `@concordium/node-sdk` exposes the full API of the SDK. -- `@concordium/node-sdk/cis0` entrypoint exposes functionality for working -with contracts adhering to the -[CIS-0](https://proposals.concordium.software/CIS/cis-0.html) standard. -- `@concordium/node-sdk/cis2` entrypoint exposes functionality for working -with contracts adhering to the -[CIS-2](https://proposals.concordium.software/CIS/cis-2.html) standard. -- `@concordium/node-sdk/cis4` entrypoint exposes functionality for working -with contracts adhering to the -[CIS-4](https://proposals.concordium.software/CIS/cis-4.html) standard. -- `@concordium/node-sdk/client` entrypoint exposes the **(deprecated)** -grpc client for interacting with a nodes GPRCv1 interface. -- `@concordium/node-sdk/grpc` entrypoint exposes the grpc client for -interacting with a nodes GRPCv2 interface. -- `@concordium/node-sdk/id` entrypoint exposes functionality for working -with ID proofs. -- `@concordium/node-sdk/schema` entrypoint exposes functionality for working -with smart contract schemas, i.e.(de)serializing types using a smart contract schema. - - This uses the wasm entrypoint at `@concordium/rust-bindings/dapp`. -- `@concordium/node-sdk/types` entrypoint exposes functionality for working -with concordium domain types. -- `@concordium/node-sdk/wasm` entrypoint exposes a variety of functionality for -working with concordium domain types, which requires WASM. - - This uses the wasm entrypoint at `@concorodium/rust-bindings/wallet`. -- `@concordium/node-sdk/web3-id` entrypoint exposes functionality for working -with web3-id proofs. - ## Common SDK version 5 to 6 (Web 2->3) (Node 5->6) Some classes and types have been renamed or changed, and should be update if used. diff --git a/docs/tsconfig.json b/docs/tsconfig.json index 3989e2a62..d92fe122c 100644 --- a/docs/tsconfig.json +++ b/docs/tsconfig.json @@ -5,7 +5,8 @@ "moduleResolution": "NodeNext" }, "include": [ - "../packages/**/*" + "../packages/**/*", + "./typedoc.config.cjs" ], "exclude": [ "../packages/ccd-js-gen/**/*" diff --git a/docs/typedoc.config.cjs b/docs/typedoc.config.cjs new file mode 100644 index 000000000..89964e4dd --- /dev/null +++ b/docs/typedoc.config.cjs @@ -0,0 +1,79 @@ +/* eslint-disable @typescript-eslint/no-var-requires */ +const path = require('node:path'); + +module.exports = { + name: 'Concordium JS-SDKs', + out: path.resolve(__dirname, '../typedoc'), + entryPointStrategy: 'expand', + entryPoints: [ + path.resolve(__dirname, '../packages/sdk/src/index.ts'), + path.resolve(__dirname, '../packages/sdk/src/nodejs/index.ts'), + ], + tsconfig: path.resolve(__dirname, '../tsconfig.json'), + readme: path.resolve(__dirname, './pages/documentation.md'), + plugin: [ + '@knodes/typedoc-plugin-code-blocks', + '@knodes/typedoc-plugin-pages', + 'typedoc-plugin-merge-modules', + ], + mergeModulesMergeMode: 'module', + pluginCodeBlocks: { + source: path.resolve(__dirname, '../examples'), + }, + pluginPages: { + source: path.resolve(__dirname, './pages'), + pages: [ + { + name: 'Concordium JS-SDKs', + children: [ + { + name: 'CIS2-Contracts', + source: 'cis2-contracts.md', + }, + { + name: 'Identity Proofs', + source: 'identity-proofs.md', + }, + { + name: 'Runnable Examples', + source: 'runnable-examples.md', + }, + { + name: 'Transactions', + source: 'transactions.md', + }, + { + name: 'Utility Functions', + source: 'utility-functions.md', + }, + { + name: 'Miscellaneous Pages', + childrenDir: 'misc-pages', + children: [ + { + name: 'Account Creation', + source: 'account-creation.md', + }, + { + name: 'Optimizing bundled applications', + source: 'bundler-optimizations.md', + }, + { + name: 'GRPCv1 to GRPCv2 Migration Guide', + source: 'grpc-migration.md', + }, + { + name: 'Old GRPC-Client', + source: 'grpc-v1.md', + }, + { + name: 'Upgrade Guide', + source: 'upgrade-guide.md', + }, + ], + }, + ], + }, + ], + }, +}; diff --git a/docs/typedoc.json b/docs/typedoc.json deleted file mode 100644 index b1687892e..000000000 --- a/docs/typedoc.json +++ /dev/null @@ -1,73 +0,0 @@ -{ - "name": "Concordium JS-SDKs", - "out": "../typedoc", - "entryPointStrategy": "expand", - "entryPoints": [ - "../packages/sdk/src/index.ts", - "../packages/sdk/src/nodejs/index.ts" - ], - "tsconfig": "../tsconfig.json", - "readme": "./pages/documentation.md", - "plugin": [ - "@knodes/typedoc-plugin-code-blocks", - "@knodes/typedoc-plugin-pages", - "typedoc-plugin-merge-modules" - ], - "mergeModulesMergeMode": "module", - "pluginPages": { - "source": "docs/pages", - "pages": [ - { - "name": "Concordium JS-SDKs", - "children": [ - { - "name": "CIS2-Contracts", - "source": "cis2-contracts.md" - }, - { - "name": "Identity Proofs", - "source": "identity-proofs.md" - }, - { - "name": "Runnable Examples", - "source": "runnable-examples.md" - }, - { - "name": "Transactions", - "source": "transactions.md" - }, - { - "name": "Utility Functions", - "source": "utility-functions.md" - }, - { - "name": "Miscellaneous Pages", - "childrenDir": "misc-pages", - "children": [ - { - "name": "Account Creation", - "source": "account-creation.md" - }, - { - "name": "Optimizing bundled applications", - "source": "bundler-optimizations.md" - }, - { - "name": "GRPCv1 to GRPCv2 Migration Guide", - "source": "grpc-migration.md" - }, - { - "name": "Old GRPC-Client", - "source": "grpc-v1.md" - }, - { - "name": "Upgrade Guide", - "source": "upgrade-guide.md" - } - ] - } - ] - } - ] - } -}