1169: Setup TypeDoc with Docusaurus and add docs for API reference

docs/README.md

@@ -1,25 +1,29 @@
-# Website
+# Puffer SDK Docs
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
+> Note: This is a workspace package, so run all commands from the root of the repo.
+
 ### Installation
 
-```
-$ yarn
+```sh
+# Switch to repo root if needed.
+cd ../
+pnpm install
 ```
 
 ### Local Development
 
-```
-$ yarn start
+```sh
+pnpm docs:start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
-```
-$ yarn build
+```sh
+pnpm docs:build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
@@ -28,14 +32,14 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
-$ USE_SSH=true yarn deploy
+```sh
+USE_SSH=true pnpm docs:deploy
 ```
 
 Not using SSH:
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
+```sh
+GIT_USER=<Your GitHub username> pnpm docs:deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/api/index.md

@@ -0,0 +1,6 @@
+# API Reference
+
+## Modules
+
+- [puffer-client](puffer-client.md)
+- [puffer-client-helpers](puffer-client-helpers.md)

docs/docs/api/puffer-client-helpers.md

@@ -0,0 +1,99 @@
+# puffer-client-helpers
+
+## Classes
+
+### PufferClientHelpers
+
+Helper methods for the main `PufferClient`.
+
+#### Constructors
+
+##### new PufferClientHelpers()
+
+> **new PufferClientHelpers**(): [`PufferClientHelpers`](puffer-client-helpers.md#pufferclienthelpers)
+
+###### Returns
+
+[`PufferClientHelpers`](puffer-client-helpers.md#pufferclienthelpers)
+
+#### Methods
+
+##### createPublicClient()
+
+> `static` **createPublicClient**(`config`): `object`
+
+Helper method for creating a public client based on the
+configuration
+
+###### Parameters
+
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `config` | [`ClientConfig`](puffer-client-helpers.md#clientconfig) | Configuration for the public client. |
+
+###### Returns
+
+`object`
+
+The public client created with viem.
+
+###### Source
+
+[lib/api/puffer-client-helpers.ts:31](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client-helpers.ts#L31)
+
+##### createWalletClient()
+
+> `static` **createWalletClient**(`config`): `object`
+
+Helper method for creating a wallet client based on the
+configuration
+
+###### Parameters
+
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `config` | [`ClientConfig`](puffer-client-helpers.md#clientconfig) | Configuration for the wallet client. |
+
+###### Returns
+
+`object`
+
+The wallet client created with viem.
+
+###### Source
+
+[lib/api/puffer-client-helpers.ts:45](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client-helpers.ts#L45)
+
+##### extractTransportConfig()
+
+> `static` `private` **extractTransportConfig**(`config`): `Transport`
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `config` | [`ClientConfig`](puffer-client-helpers.md#clientconfig) |
+
+###### Returns
+
+`Transport`
+
+###### Source
+
+[lib/api/puffer-client-helpers.ts:52](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client-helpers.ts#L52)
+
+## Type Aliases
+
+### ClientConfig
+
+> **ClientConfig**: `object` & `object` \| `object`
+
+#### Type declaration
+
+##### chain
+
+> **chain**: `Chain`
+
+#### Source
+
+[lib/api/puffer-client-helpers.ts:13](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client-helpers.ts#L13)

docs/docs/api/puffer-client.md

@@ -0,0 +1,109 @@
+# puffer-client
+
+## Classes
+
+### PufferClient
+
+The core class and the main entry point of the Puffer SDK.
+
+#### Constructors
+
+##### new PufferClient()
+
+> **new PufferClient**(`chain`, `walletClient`?, `publicClient`?): [`PufferClient`](puffer-client.md#pufferclient)
+
+Create the Puffer Client.
+
+###### Parameters
+
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `chain` | `Chain` | Chain to use for the client. |
+| `walletClient`? | `object` | The wallet client to use for wallet interactions. |
+| `publicClient`? | `object` | The public client to use for public interactions. |
+
+###### Returns
+
+[`PufferClient`](puffer-client.md#pufferclient)
+
+###### Source
+
+[lib/api/puffer-client.ts:32](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client.ts#L32)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| `chainAbis` | `private` | `ValueOf`\<`object`\> |
+| `chainAddresses` | `private` | `ValueOf`\<`object`\> |
+| `publicClient` | `private` | `object` |
+| `viemChain` | `private` | `Chain` |
+| `walletClient` | `private` | `object` |
+
+#### Methods
+
+##### depositETH()
+
+> **depositETH**(`walletAddress`): `object`
+
+Deposit ETH to the given wallet address. This doesn't make the
+transaction but returns two methods namely `transact` and
+`estimate`.
+
+###### Parameters
+
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `walletAddress` | \`0x$\{string\}\` | Wallet address to get the ETH from. |
+
+###### Returns
+
+`object`
+
+`transact: (value: bigint) => Promise<Address>` - Used to
+make the transaction with the given value.
+
+`estimate: () => Promise<bigint>` - Gas estimate of the
+transaction.
+
+###### estimate()
+
+> **estimate**: () => `Promise`\<`bigint`\>
+
+###### Returns
+
+`Promise`\<`bigint`\>
+
+###### transact()
+
+> **transact**: (`value`) => `Promise`\<\`0x$\{string\}\`\>
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `value` | `bigint` |
+
+###### Returns
+
+`Promise`\<\`0x$\{string\}\`\>
+
+###### Source
+
+[lib/api/puffer-client.ts:76](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client.ts#L76)
+
+##### requestAddresses()
+
+> **requestAddresses**(): `Promise`\<`RequestAddressesReturnType`\>
+
+Request addresses from the wallet.
+
+###### Returns
+
+`Promise`\<`RequestAddressesReturnType`\>
+
+An array of wallet addresses.
+
+###### Source
+
+[lib/api/puffer-client.ts:60](https://github.com/PufferFinance/puffer-smart-contract-lib/blob/7435e1fb1bddb7203930f076ca6a2db2b0c715f9/lib/api/puffer-client.ts#L60)

docs/docs/guides/depositing-eth.md

@@ -39,7 +39,6 @@ const gasEstimate = await estimate();
 const txHash = await transact(weiAmount);
 ```
 
-
 Alternatively, you can set the pufETH recipient to a different address.
 
 ```ts

docs/docusaurus.config.ts

@@ -29,6 +29,10 @@ const config: Config = {
     locales: ['en'],
   },
 
+  markdown: {
+    format: 'detect',
+  },
+
   presets: [
     [
       'classic',
@@ -49,13 +53,35 @@ const config: Config = {
   ],
 
   themeConfig: {
+    tableOfContents: {
+      // For API docs generated method headings.
+      maxHeadingLevel: 5,
+    },
     navbar: {
       title: 'Puffer SDK Docs',
       logo: {
         alt: 'Puffer Logo',
         src: 'img/logo.svg',
       },
       items: [
+        {
+          type: 'doc',
+          position: 'left',
+          docId: 'getting-started',
+          label: 'Getting Started',
+        },
+        {
+          type: 'doc',
+          position: 'left',
+          docId: 'guides/index',
+          label: 'Guides',
+        },
+        {
+          type: 'doc',
+          position: 'left',
+          docId: 'api/index',
+          label: 'API Reference',
+        },
         {
           href: 'https://github.com/PufferFinance/puffer-sdk',
           label: 'GitHub',
@@ -110,7 +136,31 @@ const config: Config = {
       darkTheme: prismThemes.dracula,
     },
   } satisfies Preset.ThemeConfig,
-  plugins: ['@easyops-cn/docusaurus-search-local'],
+  plugins: [
+    '@easyops-cn/docusaurus-search-local',
+    // Plugin for generating API docs.
+    [
+      'docusaurus-plugin-typedoc',
+      // https://typedoc-plugin-markdown.org/plugins/docusaurus/options
+      // https://typedoc-plugin-markdown.org/docs/options
+      {
+        entryPoints: '../lib/api',
+        exclude: '**/*+(test|spec|index).ts',
+        entryPointStrategy: 'expand',
+        tsconfig: '../tsconfig.json',
+        readme: 'none',
+        outputFileStrategy: 'modules',
+        excludeExternals: true,
+        sidebar: { autoConfiguration: false },
+        textContentMappings: {
+          'title.indexPage': 'API Reference',
+        },
+        parametersFormat: 'table',
+        enumMembersFormat: 'table',
+        propertiesFormat: 'table',
+      },
+    ],
+  ],
 };
 
 export default config;

docs/package.json

@@ -29,6 +29,9 @@
     "@docusaurus/tsconfig": "3.3.2",
     "@docusaurus/types": "3.3.2",
     "@types/react": "^18.3.2",
+    "docusaurus-plugin-typedoc": "^1.0.1",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^4.0.2",
     "typescript": "~5.2.2"
   },
   "browserslist": {