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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
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
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
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Expand Down
12 changes: 11 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,30 @@ 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
```

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
Expand Down
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
!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',

// 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 on lines +287 to +288
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

⚠️ Potential issue

Fix naming inconsistency for ethers adapters

The source paths use ether-v5-adapter and ether-v6-adapter (without 's'), while the output paths and sidebar labels use ethers (with 's'). This inconsistency could cause confusion.

Either rename the source directories to include the 's' or update the output paths and labels to match the source naming:

-        out: 'cow-protocol/reference/sdks/provider-adapters/sdk-ethers-v5-adapter',
+        out: 'cow-protocol/reference/sdks/provider-adapters/sdk-ether-v5-adapter',
         sidebar: {
-          categoryLabel: 'sdk-ethers-v5-adapter',
+          categoryLabel: 'sdk-ether-v5-adapter',

Also applies to: 291-291, 293-293, 304-305, 308-308, 310-310

🤖 Prompt for AI Agents 
In docusaurus.config.ts around lines 287-288 and also lines 291, 293, 304-305,
308, and 310, there is a naming inconsistency between 'ether-v5-adapter'
(without 's') in source paths and 'ethers' (with 's') in output paths and
sidebar labels. To fix this, either rename all source directories to include the
's' consistently as 'ethers-v5-adapter' and 'ethers-v6-adapter', or update all
output paths and sidebar labels to use 'ether' without the 's' to match the
source directories. Ensure all references are consistent across these lines.

Copy link
Contributor

@alfetopito alfetopito Aug 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@jeffersonBastos shouldn't it be ethers instead?

Copy link
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!

Copy link
Author

Choose a reason for hiding this comment

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

@alfetopito Yes, it should all be "ethers" actually.
The one without the "s" is the folder name in the SDK. Would you like me to make that change?


// 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,
},
},
],
Expand Down
Loading