Improve Docs (#46)

* fix: gradient on docs home * chore: reorganize docs * feat: add head meta for docs * feat: docs progress * feat: added a bunch of docs * feat: removed bolt11 from function names * chore: changeset * fix: dead links
fedimint · Sep 27, 2024 · ada54ce · ada54ce
1 parent 7ea5b6d
commit ada54ce
Show file tree

Hide file tree

Showing 53 changed files with 549 additions and 763 deletions.
diff --git a/.changeset/rotten-fireants-invent.md b/.changeset/rotten-fireants-invent.md
@@ -0,0 +1,5 @@
+---
+'@fedimint/core-web': patch
+---
+
+Shortened lightning function names to omit "Bolt11". (createBolt11Invoice --> createInvoice
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1 @@
+@alexlwn123
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1 @@
+[View Contributing Guide on our docs page](https://web.fedimint.org/dev/contributing)
diff --git a/.github/README.md b/.github/README.md
@@ -0,0 +1,43 @@
+![GitHub License](https://img.shields.io/github/license/fedimint/fedimint-web-sdk?style=plastic&color=blue&link=https%3A%2F%2Fgithub.com%2Ffedimint%2Ffedimint-web-sdk%2Fblob%2Fmain%2FLICENSE)
+![NPM Version (latest)](<https://img.shields.io/npm/v/%40fedimint%2Fcore-web?style=plastic&logo=npm&logoColor=rgb(187%2C%2054%2C%2057)&label=%40fedimint%2Fcore-web&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40fedimint%2Fcore-web>)
+![Docs Workflow](https://img.shields.io/github/actions/workflow/status/fedimint/fedimint-web-sdk/deploy-docs.yml?style=plastic&label=Docs%20Site&color=%2303b1fc&link=https%3A%2F%2Fweb.fedimint.org%2F)
+![Release Workflow](https://img.shields.io/github/actions/workflow/status/fedimint/fedimint-web-sdk/.github%2Fworkflows%2Fchangesets.yml?style=plastic&label=Test%20%26%20Release&color=green)
+
+# Fedimint Web SDK Monorepo
+
+### Docs Site: [web.fedimint.org](https://web.fedimint.org)
+
+---
+
+### Structure
+
+This monorepo is structured as a pnpm workspace. There are some helpful scripts in the root `package.json` to help manage the workspace.
+
+```bash
+fedimint-web-sdk
+├── README.md
+├── examples
+│   ├── vite-core
+│   └── bare-js
+└── packages
+    ├── core-web
+    ├── react
+    ├── wasm-web
+    └── wasm-bundler
+```
+
+### Packages
+
+- [`core-web`](https://web.fedimint.org/docs/core/getting-started): Provides a typescript interface for the Fedimint client wasm.
+- `react`: TBD - React components and hooks for interacting with the Fedimint client
+- [`wasm-web`](../packages/wasm-web/README.md): Not intended for direct use. Contains the wasm pack output (target web) for the Fedimint client wasm.
+- [`wasm-bundler`](../packages/wasm-bundler/README.md): Not intended for direct use. Contains the wasm pack output (target bundler) for the Fedimint client wasm.
+
+### Examples
+
+- [`vite-core`](../examples/vite-core/README.md): Simple example of how to use the `core-web` package within a React app bundled with Vite.
+- [`bare-js`](../examples/bare-js/README.md): Simple example of how to use the `core-web` package in a bare javascript environment (no bundler)
+
+### Credit
+
+Used the [wagmi](https://github.com/wevm/wagmi) library as a reference for the repo's structure.
diff --git a/README.md b/README.md
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -8,9 +8,36 @@ export default withMermaid({
   ignoreDeadLinks: false,
   lang: 'en-US',
   lastUpdated: true,
-  // base: '/fedimint-web-sdk/',
+  head: [
+    [
+      'meta',
+      {
+        name: 'keywords',
+        content: 'bitcoin, lightning, ecash, fedimint, typescript, wasm, react',
+      },
+    ],
+    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    ['meta', { name: 'theme-color', content: '#346cff' }],
+    // Open Graph
+    ['meta', { property: 'og:type', content: 'website' }],
+    [
+      'meta',
+      {
+        property: 'og:image',
+        content: 'https://web.fedimint.org/og.png',
+      },
+    ],
+    ['meta', { property: 'og:url', content: 'https://web.fedimint.org' }],
+    // Twitter
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:creator', content: '@fedimint' }],
+    [
+      'meta',
+      { name: 'twitter:image', content: 'https://web.fedimint.org/og.png' },
+    ],
+    ['meta', { name: 'twitter:site', content: 'https://web.fedimint.org' }],
+  ],
   themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
     editLink: {
       pattern:
         'https://github.com/fedimint/fedimint-web-sdk/edit/main/docs/:path',
@@ -21,16 +48,14 @@ export default withMermaid({
         'Released under the <a href="https://github.com/fedimint/fedimint-web-sdk/blob/main/LICENSE">MIT License</a>.',
     },
     nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Core', link: '/core/getting-started' },
-      { text: 'Packages', link: '/packages' },
+      { text: 'Documentation', link: '/core/getting-started' },
       { text: 'Examples', link: '/examples' },
       {
         text: 'More',
         items: [
           {
             text: 'Contributing',
-            link: '/dev/contributing',
+            link: '/core/dev/contributing',
           },
           {
             text: 'Discussions ',
@@ -55,6 +80,10 @@ export default withMermaid({
         icon: 'github',
         link: 'https://github.com/fedimint/fedimint-web-sdk',
       },
+      {
+        icon: 'npm',
+        link: 'https://www.npmjs.com/package/@fedimint/core-web',
+      },
       {
         icon: 'discord',
         link: 'https://chat.fedimint.org',

diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts
@@ -1,38 +1,116 @@
 import type { DefaultTheme } from 'vitepress'
-import typedocSidebar from '../core/api/typedoc-sidebar.json'
 
 export function getSidebar() {
   return {
     '/core/': [
       {
-        text: 'Getting Started',
+        base: '/core/',
+        text: 'Introduction',
         items: [
-          { text: 'Overview', link: '/core/overview' },
-          { text: 'Installation', link: '/core/getting-started' },
-          { text: 'Architecture', link: '/core/architecture' },
+          { text: 'Overview', link: 'overview' },
+          { text: 'Getting Started', link: 'getting-started' },
+          { text: 'Architecture', link: 'architecture' },
         ],
       },
+      ...FedimintWalletSidebar,
       {
-        text: 'API',
-        link: '/core/api/index.md',
-        items: typedocSidebar,
+        text: 'Dev',
+        base: '/core/dev/',
+        items: [
+          { text: 'Contributing', link: 'contributing' },
+          { text: 'Testing', link: 'testing' },
+        ],
+      },
+    ],
+  } satisfies DefaultTheme.Sidebar
+}
+
+const FedimintWalletSidebar = [
+  {
+    text: 'FedimintWallet',
+    link: '.',
+    base: '/core/FedimintWallet/',
+    items: [
+      {
+        text: 'new FedimintWallet()',
+        link: 'constructor',
+      },
+      {
+        text: 'setLogLevel()',
+        link: 'setLogLevel',
+      },
+      {
+        text: 'joinFederation()',
+        link: 'joinFederation',
+      },
+      {
+        text: 'initialize()',
+        link: 'initialize',
       },
       {
-        text: 'TEMP',
+        text: 'isOpen()',
+        link: 'isOpen',
+      },
+      {
+        text: 'cleanup()',
+        link: 'cleanup',
+      },
+      {
+        text: 'BalanceService',
+        base: '/core/FedimintWallet/BalanceService/',
         items: [
-          { text: 'Markdown Examples', link: '/temp/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/temp/api-examples' },
+          { text: 'getBalance()', link: 'getBalance' },
+          { text: 'subscribeBalance()', link: 'subscribeBalance' },
         ],
       },
-    ],
-    '/dev/': [
       {
-        text: 'Dev',
+        text: 'LightningService',
+        base: '/core/FedimintWallet/LightningService/',
         items: [
-          { text: 'Contributing', link: '/dev/contributing' },
-          { text: 'Testing', link: '/dev/testing' },
+          { text: 'Docs TODO' },
+          // { text: 'payInvoice()', link: 'payInvoice' },
+          // { text: 'createInvoice()', link: 'createInvoice' },
+          // {
+          //   text: 'createInvoiceWithGateway()',
+          //   link: 'createInvoiceWithGateway',
+          // },
+          // { text: 'subscribeInvoiceStatus()', link: 'subscribeInvoiceStatus' },
+          // { text: 'subscribeLnPay()', link: 'subscribeLnPay' },
+          // { text: 'subscribeLnReceive()', link: 'subscribeLnReceive' },
+          // { text: 'listGateways()', link: 'listGateways' },
+          // { text: 'getGateway()', link: 'getGateway' },
+          // { text: 'updateGatewayCache()', link: 'updateGatewayCache' },
         ],
       },
+      {
+        text: 'MintService',
+        base: '/core/FedimintWallet/MintService/',
+        items: [{ text: 'Docs TODO' }],
+      },
+      {
+        text: 'FederationService',
+        base: '/core/FedimintWallet/FederationService/',
+        items: [{ text: 'Docs TODO' }],
+      },
+      {
+        text: 'RecoveryService',
+        base: '/core/FedimintWallet/RecoveryService/',
+        items: [{ text: 'Docs TODO' }],
+      },
     ],
-  } satisfies DefaultTheme.Sidebar
-}
+  },
+  {
+    text: 'Type Aliases',
+    collapsed: true,
+    base: '/core/type-aliases/',
+    items: [
+      { text: 'CreateResponse', link: 'CreateResponse' },
+      { text: 'FeeToAmount', link: 'FeeToAmount' },
+      { text: 'LightningGateway', link: 'LightningGateway' },
+      { text: 'LnPayState', link: 'LnPayState' },
+      { text: 'OutgoingLightningPayment', link: 'OutgoingLightningPayment' },
+      { text: 'PayType', link: 'PayType' },
+      { text: 'RouteHint', link: 'RouteHint' },
+    ],
+  },
+]
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,27 @@
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    rgba(189, 52, 254, 0.3) 50%,
+    rgba(71, 202, 255, 0.3) 50%
+  );
+  --vp-home-hero-image-filter: blur(68px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(88px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(120px);
+  }
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme
diff --git a/docs/core/FedimintWallet/BalanceService/getBalance.md b/docs/core/FedimintWallet/BalanceService/getBalance.md
@@ -0,0 +1,14 @@
+# Get Balance
+
+### `balance.getBalance()`
+
+Get the current balance of the wallet.
+
+```ts
+// const wallet = new FedimintWallet()
+// wallet.open()
+
+const mSats = await wallet.balance.getBalance()
+
+// 1000 mSats = 1 satoshi
+```
diff --git a/docs/core/FedimintWallet/BalanceService/subscribeBalance.md b/docs/core/FedimintWallet/BalanceService/subscribeBalance.md
@@ -0,0 +1,18 @@
+# Subscribe Balance
+
+### `balance.subscribeBalance()` <Badge type="info" text="Streaming" />
+
+Subscribe to balance updates as they occur.
+
+```ts
+// const wallet = new FedimintWallet()
+// wallet.open()
+
+const unsubscribe = wallet.balance.subscribeBalance((mSats) => {
+  console.log('Balance updated:', mSats)
+  // 1000 mSats = 1 satoshi
+})
+
+// ...Cleanup Later
+unsubscribe()
+```
diff --git a/docs/core/FedimintWallet/cleanup.md b/docs/core/FedimintWallet/cleanup.md
@@ -0,0 +1,5 @@
+This guide hasn't been written yet.
+
+If you'd like to contribute, please open a PR!
+
+You can use the `Edit This Page` link below.