From 435eba3f0129142c627959721df4cd2f54842313 Mon Sep 17 00:00:00 2001 From: Jefferson Bastos Date: Thu, 31 Jul 2025 21:00:16 -0300 Subject: [PATCH 1/2] feat(sdk-docs): add documentation configuration for SDK monorepo --- docs/cow-amm/tutorials/cow-amm-for-solvers.md | 4 +- .../reference/core/intents/app_data.mdx | 2 +- docs/cow-protocol/reference/sdks/.gitignore | 7 + .../sdks/core-utilities/_category_.json | 8 + .../sdks/protocol-components/_category_.json | 8 + .../sdks/provider-adapters/_category_.json | 8 + docs/governance/fees/fees.md | 2 +- docusaurus.config.ts | 254 +++++++++++++++++- package.json | 10 +- 9 files changed, 287 insertions(+), 16 deletions(-) create mode 100644 docs/cow-protocol/reference/sdks/core-utilities/_category_.json create mode 100644 docs/cow-protocol/reference/sdks/protocol-components/_category_.json create mode 100644 docs/cow-protocol/reference/sdks/provider-adapters/_category_.json diff --git a/docs/cow-amm/tutorials/cow-amm-for-solvers.md b/docs/cow-amm/tutorials/cow-amm-for-solvers.md index af6d3807..eb1043d4 100644 --- a/docs/cow-amm/tutorials/cow-amm-for-solvers.md +++ b/docs/cow-amm/tutorials/cow-amm-for-solvers.md @@ -77,11 +77,11 @@ This order can be included in a batch as any other CoW Protocol orders with two - One of the pre-interactions must set the commitment by calling `BCoWPool.commit(hash)`. - Must contain at most one order from the AMM in the same batch. -::note +:::note Solvers using the non co-located driver should add a [`JitTrade`](https://github.com/cowprotocol/services/blob/95ecc4e01b7fd06ec0b71c6486cb2cdd962e5040/crates/solvers/openapi.yml#L744C1-L774C52) and a [`preInteraction`](https://github.com/cowprotocol/services/blob/95ecc4e01b7fd06ec0b71c6486cb2cdd962e5040/crates/solvers/openapi.yml#L920C1-L925C46) to their solution. -:: +::: ### Surplus diff --git a/docs/cow-protocol/reference/core/intents/app_data.mdx b/docs/cow-protocol/reference/core/intents/app_data.mdx index f9efa182..dae7b1e8 100644 --- a/docs/cow-protocol/reference/core/intents/app_data.mdx +++ b/docs/cow-protocol/reference/core/intents/app_data.mdx @@ -4,7 +4,7 @@ sidebar_position: 1 --- import CodeBlock from '@theme/CodeBlock'; -import appDataSchema from '/external/app-data/schemas/v1.3.0.json'; +import appDataSchema from '/external/cow-sdk/packages/app-data/schemas/v1.3.0.json'; import JSONSchemaViewer from '@theme/JSONSchemaViewer'; # Application specific data diff --git a/docs/cow-protocol/reference/sdks/.gitignore b/docs/cow-protocol/reference/sdks/.gitignore index 7c53090f..c59a53d8 100644 --- a/docs/cow-protocol/reference/sdks/.gitignore +++ b/docs/cow-protocol/reference/sdks/.gitignore @@ -1,3 +1,10 @@ **/* !_category_.json +!_category_.yml +!provider-adapters/ +!provider-adapters/_category_.json +!core-utilities/ +!core-utilities/_category_.json +!protocol-components/ +!protocol-components/_category_.json !.gitignore \ No newline at end of file diff --git a/docs/cow-protocol/reference/sdks/core-utilities/_category_.json b/docs/cow-protocol/reference/sdks/core-utilities/_category_.json new file mode 100644 index 00000000..f7b9a188 --- /dev/null +++ b/docs/cow-protocol/reference/sdks/core-utilities/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Core Utilities", + "position": 3, + "link": { + "type": "generated-index", + "description": "Core utility modules for the Cow Protocol SDK" + } +} diff --git a/docs/cow-protocol/reference/sdks/protocol-components/_category_.json b/docs/cow-protocol/reference/sdks/protocol-components/_category_.json new file mode 100644 index 00000000..cdd3c8e4 --- /dev/null +++ b/docs/cow-protocol/reference/sdks/protocol-components/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Protocol Components", + "position": 4, + "link": { + "type": "generated-index", + "description": "Protocol-specific components and modules" + } +} diff --git a/docs/cow-protocol/reference/sdks/provider-adapters/_category_.json b/docs/cow-protocol/reference/sdks/provider-adapters/_category_.json new file mode 100644 index 00000000..43531de3 --- /dev/null +++ b/docs/cow-protocol/reference/sdks/provider-adapters/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Provider Adapters", + "position": 2, + "link": { + "type": "generated-index", + "description": "Provider adapters for different Ethereum libraries" + } +} diff --git a/docs/governance/fees/fees.md b/docs/governance/fees/fees.md index 982b815c..f93d61c2 100644 --- a/docs/governance/fees/fees.md +++ b/docs/governance/fees/fees.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Fees -:::Note +:::note This documentation refers to CoW Protocol fees. Builders connected to MEV blocker also pay a fee, which is discussed [here](/mevblocker/builders/fees/subscription-fees). diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 1fb8aba4..5f8cc5a8 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -77,9 +77,11 @@ const config: Config = { { id: 'cow-sdk', // TypeDoc options - entryPoints: ['./external/cow-sdk/src/index.ts'], - tsconfig: './external/cow-sdk/tsconfig.json', - + entryPoints: [ + './external/cow-sdk/packages/sdk/src/typedoc-entry.ts', + ], + tsconfig: './external/cow-sdk/packages/sdk/tsconfig.json', + // Plugin options out: 'cow-protocol/reference/sdks/cow-sdk', sidebar: { @@ -89,20 +91,260 @@ const config: Config = { }, }, ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-trading', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/trading/src/index.ts'], + tsconfig: './external/cow-sdk/packages/trading/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-trading', + sidebar: { + categoryLabel: 'sdk-trading', + collapsed: true, + position: 1, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-order-book', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/order-book/src/index.ts'], + tsconfig: './external/cow-sdk/packages/order-book/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-order-book', + sidebar: { + categoryLabel: 'sdk-order-book', + collapsed: true, + position: 2, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'contracts-ts', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/contracts-ts/src/index.ts'], + tsconfig: './external/cow-sdk/packages/contracts-ts/tsconfig.json', + excludeNotDocumented: true, + + // Plugin options + out: 'cow-protocol/reference/sdks/core-utilities/sdk-contracts-ts', + sidebar: { + categoryLabel: 'sdk-contracts-ts', + collapsed: true, + position: 3, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-order-signing', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/order-signing/src/index.ts'], + tsconfig: './external/cow-sdk/packages/order-signing/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-order-signing', + sidebar: { + categoryLabel: 'sdk-order-signing', + collapsed: true, + position: 3, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-cow-shed', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/cow-shed/src/index.ts'], + tsconfig: './external/cow-sdk/packages/cow-shed/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-cow-shed', + sidebar: { + categoryLabel: 'sdk-cow-shed', + collapsed: true, + position: 4, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-composable', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/composable/src/index.ts'], + tsconfig: './external/cow-sdk/packages/composable/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-composable', + sidebar: { + categoryLabel: 'sdk-composable', + collapsed: true, + position: 5, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-bridging', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/bridging/src/index.ts'], + tsconfig: './external/cow-sdk/packages/bridging/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-bridging', + sidebar: { + categoryLabel: 'sdk-bridging', + collapsed: true, + position: 6, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-subgraph', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/subgraph/src/index.ts'], + tsconfig: './external/cow-sdk/packages/subgraph/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-subgraph', + sidebar: { + categoryLabel: 'sdk-subgraph', + collapsed: true, + position: 7, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-weiroll', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/weiroll/src/index.ts'], + tsconfig: './external/cow-sdk/packages/weiroll/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/protocol-components/sdk-weiroll', + sidebar: { + categoryLabel: 'sdk-weiroll', + collapsed: true, + position: 8, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-common', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/common/src/index.ts'], + tsconfig: './external/cow-sdk/packages/common/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/core-utilities/sdk-common', + sidebar: { + categoryLabel: 'sdk-common', + collapsed: true, + position: 1, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-config', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/config/src/index.ts'], + tsconfig: './external/cow-sdk/packages/config/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/core-utilities/sdk-config', + sidebar: { + categoryLabel: 'sdk-config', + collapsed: true, + position: 2, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-ethers-v5-adapter', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/providers/ether-v5-adapter/src/index.ts'], + tsconfig: './external/cow-sdk/packages/providers/ether-v5-adapter/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/provider-adapters/sdk-ethers-v5-adapter', + sidebar: { + categoryLabel: 'sdk-ethers-v5-adapter', + collapsed: true, + position: 1, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-ethers-v6-adapter', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/providers/ether-v6-adapter/src/index.ts'], + tsconfig: './external/cow-sdk/packages/providers/ether-v6-adapter/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/provider-adapters/sdk-ethers-v6-adapter', + sidebar: { + categoryLabel: 'sdk-ethers-v6-adapter', + collapsed: true, + position: 2, + }, + }, + ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'sdk-viem-adapter', + // TypeDoc options + entryPoints: ['./external/cow-sdk/packages/providers/viem-adapter/src/index.ts'], + tsconfig: './external/cow-sdk/packages/providers/viem-adapter/tsconfig.json', + + // Plugin options + out: 'cow-protocol/reference/sdks/provider-adapters/sdk-viem-adapter', + sidebar: { + categoryLabel: 'sdk-viem-adapter', + collapsed: true, + position: 3, + }, + excludeExternals: true, + }, + ], [ 'docusaurus-plugin-typedoc', { id: 'app-data', // TypeDoc options - entryPoints: ['./external/app-data/src/index.ts'], - tsconfig: './external/app-data/tsconfig.json', + entryPoints: ['./external/cow-sdk/packages/app-data/src/index.ts'], + tsconfig: './external/cow-sdk/packages/app-data/tsconfig.json', // Plugin options out: 'cow-protocol/reference/sdks/app-data', sidebar: { categoryLabel: 'app-data', collapsed: true, - position: 2, + position: 5, }, }, ], diff --git a/package.json b/package.json index 8d25ddf8..523a1b65 100644 --- a/package.json +++ b/package.json @@ -6,11 +6,9 @@ "docusaurus": "docusaurus", "start": "docusaurus start", "git:clone:cowsdk": "cd external && rm -rf cow-sdk && git clone --depth=1 --branch=main https://github.com/cowprotocol/cow-sdk cow-sdk && rm -rf cow-sdk/.git", - "git:clone:appdata": "cd external && rm -rf app-data && git clone --depth=1 --branch=main https://github.com/cowprotocol/app-data app-data && rm -rf app-data/.git", - "build:external:cowsdk": "yarn git:clone:cowsdk && cd external/cow-sdk && yarn install --frozen --ignore-scripts && yarn codegen", - "build:external:appdata": "yarn git:clone:appdata && cd external/app-data && yarn install --frozen --ignore-scripts && yarn compile", - "build:external": "yarn build:external:cowsdk && yarn build:external:appdata", - "build": "yarn build:external && docusaurus build", + "build:external:cowsdk": "cd external/cow-sdk && pnpm install && pnpm run build", + "build:external": "yarn build:external:cowsdk", + "build": "yarn build:external && NODE_OPTIONS=\"--max-old-space-size=8192\" docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", @@ -73,4 +71,4 @@ "_comment": "https://github.com/swagger-api/swagger-ui/releases/tag/v5.18.0", "enabled": false } -} \ No newline at end of file +} From 0c599579618668504a234fb1cdf48caa83c39c80 Mon Sep 17 00:00:00 2001 From: Jefferson Bastos Date: Fri, 1 Aug 2025 15:22:58 -0300 Subject: [PATCH 2/2] chore(docs): fix pnpm dependency for build process - Add pnpm installation to Vercel build command - Update documentation to include pnpm requirement --- CONTRIBUTING.md | 8 ++++++++ README.md | 12 +++++++++++- vercel.json | 1 + 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5897ef75..e4fe16ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,14 @@ There are many ways to contribute to CoW Protocol. We welcome contributions of all kinds from anyone, whether you've been a long-time user or you are just getting started with development. +## Prerequisites + +Before contributing, make sure you have the following installed: + +- **Node.js** (version 22.14.0 or higher) +- **Yarn** (package manager) +- **pnpm** (required for external dependencies): `npm install -g pnpm` + ## Troubleshooting You can help other users in the community to solve their issues in the [CoW Protocol Discord]. diff --git a/README.md b/README.md index 2078c31c..68fe3851 100644 --- a/README.md +++ b/README.md @@ -27,13 +27,19 @@ The preview should load in a new tab. ### Installation +This project requires both Yarn and pnpm to be installed: + ```bash +# Install pnpm globally (required for external dependencies) +npm install -g pnpm + +# Install project dependencies yarn ``` ### Build -You will also need to `build` the app, to ensure external dependent projects are cloned and setup properly. +You will also need to `build` the app, to ensure external dependent projects are cloned and setup properly. This process requires pnpm to be installed globally. ```bash yarn build @@ -41,6 +47,10 @@ yarn build This command generates static content into the `build` directory and can be served using any static contents hosting service. +### Deployment + +This documentation site is automatically deployed using Vercel. When changes are pushed to the main branch, Vercel automatically builds and deploys the updated documentation. + ### Local Development ```bash diff --git a/vercel.json b/vercel.json index 68535f67..e1bf5f71 100644 --- a/vercel.json +++ b/vercel.json @@ -1,5 +1,6 @@ { "cleanUrls": true, + "buildCommand": "npm install -g pnpm && yarn build", "redirects": [ { "source": "/cow-sdk",