Skip to content

feat(sdk-docs): add documentation configuration for SDK monorepo #522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shoom3301 merged 9 commits into from
Sep 16, 2025
Merged

feat(sdk-docs): add documentation configuration for SDK monorepo #522

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
e92e6b0
Add CoW AMM Deployer tutorial
yvesfracari Mar 6, 2024
842eeb8
Apply mfw78 suggestions
yvesfracari Mar 6, 2024
5a12ea8
fix price oracle wrong uniswap version
yvesfracari Mar 18, 2024
f561cd5
Merge branch 'cowprotocol:main' into main
jeffersonBastos Jul 28, 2025
435eba3
feat(sdk-docs): add documentation configuration for SDK monorepo
jeffersonBastos Aug 1, 2025
0c59957
chore(docs): fix pnpm dependency for build process
jeffersonBastos Aug 1, 2025
64507cb
chore(docs): change ether to ethers SDK named path
jeffersonBastos Sep 16, 2025
b98b4c3
Merge branch 'main' into feat/sdk-agnostic-docs
jeffersonBastos Sep 16, 2025
bacdcac
Merge branch 'main' into feat/sdk-agnostic-docs
jeffersonBastos Sep 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/cow-amm/tutorials/cow-amm-for-solvers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/cow-protocol/reference/core/intents/app_data.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/cow-protocol/reference/sdks/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
**/*
!_category_.json
!_category_.yml
Comment thread
alfetopito marked this conversation as resolved.
!provider-adapters/
!provider-adapters/_category_.json
!core-utilities/
!core-utilities/_category_.json
!protocol-components/
!protocol-components/_category_.json
!.gitignore
8 changes: 8 additions & 0 deletions docs/cow-protocol/reference/sdks/core-utilities/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Core Utilities",
"position": 3,
"link": {
"type": "generated-index",
"description": "Core utility modules for the Cow Protocol SDK"
}
}
8 changes: 8 additions & 0 deletions docs/cow-protocol/reference/sdks/protocol-components/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Protocol Components",
"position": 4,
"link": {
"type": "generated-index",
"description": "Protocol-specific components and modules"
}
}
8 changes: 8 additions & 0 deletions docs/cow-protocol/reference/sdks/provider-adapters/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Provider Adapters",
"position": 2,
"link": {
"type": "generated-index",
"description": "Provider adapters for different Ethereum libraries"
}
}
2 changes: 1 addition & 1 deletion docs/governance/fees/fees.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
254 changes: 248 additions & 6 deletions docusaurus.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',

Comment thread
jeffersonBastos marked this conversation as resolved.
// Plugin options
out: 'cow-protocol/reference/sdks/cow-sdk',
sidebar: {
Expand All @@ -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',
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

// 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',

Comment thread
jeffersonBastos marked this conversation as resolved.
// Plugin options
out: 'cow-protocol/reference/sdks/app-data',
sidebar: {
categoryLabel: 'app-data',
collapsed: true,
position: 2,
position: 5,
},
},
],
Expand Down
10 changes: 4 additions & 6 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",

@coderabbitai coderabbitai Bot Aug 1, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Ensure pnpm is available in the build environment

The build script has switched from yarn to pnpm. Ensure that pnpm is installed and available in all environments where the documentation is built (CI/CD, local development).

🏁 Script executed:

#!/bin/bash
# Check if pnpm is available
which pnpm || echo "pnpm not found"

# Check if there's any CI configuration that might need updating
fd -e yml -e yaml . .github/workflows/ | xargs grep -l "yarn" | head -5

Length of output: 219

Add pnpm installation to CI and local setup

Our check showed that pnpm isn’t available by default (sandbox returned “pnpm not found”) and no CI workflows still reference yarn. To avoid broken builds, ensure every environment installs pnpm before running the build:external:cowsdk script:

• CI/CD workflows (e.g. in .github/workflows/*.yml):
– Add a step to install or set up pnpm, for example:
yaml - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '18' - name: Setup pnpm uses: pnpm/action-setup@v2 with: version: 'latest'
• Local development / docs:
– Update README or CONTRIBUTING to note that pnpm is required (e.g. npm install -g pnpm).

These changes will guarantee pnpm is present wherever the build script runs.

🤖 Prompt for AI Agents 
In package.json at line 9, the build script uses pnpm but pnpm is not guaranteed
to be installed in CI or local environments. To fix this, update all CI/CD
workflow YAML files (e.g., in .github/workflows/) to include steps that install
or set up pnpm before running build scripts, using actions like
pnpm/action-setup@v2. Also, update the README or CONTRIBUTING documentation to
instruct developers to install pnpm locally, for example by running npm install
-g pnpm.

@alfetopito alfetopito Aug 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point.

@jeffersonBastos if pnpm is now a requirement for the build, let's add it to the dependencies

@coderabbitai coderabbitai Bot Aug 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

@jeffersonBastos jeffersonBastos Aug 1, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch!

  • I've added the buildCommand: "npm install -g pnpm && yarn build" to vercel.json to ensure pnpm is available during Vercel deployments, and updated the documentation to instruct developers to install pnpm locally.
    However, I noticed that this project doesn't have any GitHub Actions CI workflows that run builds - the existing workflows only handle CLA, project board management, and Slack notifications. The project appears to rely entirely on Vercel for deployment.

"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",
Expand Down Expand Up @@ -73,4 +71,4 @@
"_comment": "https://github.com/swagger-api/swagger-ui/releases/tag/v5.18.0",
"enabled": false
}
}
}