Reference docs generation and plan.

dev/README.md

@@ -1,5 +1,31 @@
 # Hello sdk dev!
 
+This is your home base for how to develop on the project locally and process around that
+
+## Branches
+
+- `dev`
+  in development
+- `main`
+  "stable" what is on npm
+
+- `<name>/<issue_number>-<short_title>` (personal branches)
+  for example `frankie/i123-docs`
+
+all PRS go into `dev`
+
+## Versions
+
+The SDK version must match a compatible [`entropy-core`](https://github.com/entropyxyz/entropy-core) version.
+
+<!-- TODO: -->
+
+| module            | tag               |
+| ----------------- | ----------------- |
+| `@entropyxyz/sdk` | `main` TODO       |
+| `entropy-core`    | `release/v0.0.12` |
+
+
 ## Tests
 
 For the tests to run you **must** edit your `/etc/hosts` file, adding:
@@ -93,13 +119,32 @@ git commit --no-verify
 
 ## Publishing
 
+**Unfinished section**
+
 Always publish from `stable` branch
 
+- [ ] craft version pr for `dev` into `main`
+- [ ] `yarn burn`
+- [ ] `yarn build`
+- [ ] `yarn test`
+
+  - change logs should be hand written as apart of the version pr
+  - `yarn version patch #or major.minor.patch`
+
+  <!-- TO-DO: figure out with him an automated system -->
+
+- [ ] minimum day ideally two day before ping @johnnymatthews on version bump pr set 48 hour timer
+- [ ] after timer merge into main
+- [ ] `git push origin main --tags`
+- [ ] make sure we have a version tag
+- [ ] check out version tag
+- [ ] create a tag push to main? this might be handled by yarn needs to be checked
+- [ ] `npm publish`
+
 ```bash
 git checkout stable
 yarn burn
 yarn
-yarn build
 yarn version --patch # patch|minor|major
 npm publish
 git push origin stable --tags

package.json

@@ -3,6 +3,7 @@
   "version": "0.2.1",
   "license": "AGPL-3.0-only",
   "description": "JS SDK for entropy blockchain ",
+  "type": "module",
   "files": [
     "index.cjs",
     "index.mjs",
@@ -12,7 +13,6 @@
     "dev/**/*",
     "README.md"
   ],
-  "type": "module",
   "exports": {
     ".": {
       "import": "./index.mjs",
@@ -54,6 +54,7 @@
     "build:link": "yarn build && yarn unlink && yarn link",
     "find-deadcode": "ts-prune",
     "generate:types": "dev/bin/generate-types.sh",
+    "generate:docs": "typedoc --options typedoc.config.cjs --tsconfig tsconfig.json",
     "prepare": "husky",
     "postinstall": "patch-package",
     "prepack": "pinst --disable",
@@ -73,6 +74,7 @@
   },
   "homepage": "https://github.com/entropyxyz/sdk#readme",
   "devDependencies": {
+    "@mxssfd/typedoc-theme": "^1.1.3",
     "@polkadot/typegen": "^10.11.1",
     "@types/tape": "^5",
     "@typescript-eslint/eslint-plugin": "^5.43.0",
@@ -91,7 +93,9 @@
     "tsup": "^6.5.0",
     "tsx": "^4.9.3",
     "typedoc": "^0.25.3",
-    "typedoc-plugin-markdown": "^3.17.0",
+    "typedoc-plugin-merge-modules": "^5.1.0",
+    "typedoc-plugin-missing-exports": "^2.3.0",
+    "typedoc-plugin-rename-defaults": "^0.7.0",
     "typescript": "^4.9.5",
     "ws": "^8.17.1"
   },

src/index.ts

@@ -17,30 +17,59 @@ export async function wasmGlobalsReady () {
   await keysCryptoWaitReady
 }
 export interface EntropyOpts {
-  /** Keyring class instance object. */
+  /** Keyring used to manage all the keys Entropy uses */
   keyring: Keyring
-  /** Local or devnet endpoint for establishing a connection to validators */
+  /** A websocket endpoint for establishing a connection to validators */
   endpoint?: string
-  /** A collection of signing adapters. */
+  /** A collection of adapters used for signing messages of particular types.
+   *  These help with formatting, configuring hash functions to use, etc.
+   * */
   adapters?: { [key: string | number]: Adapter }
 }
 
 /**
- * The main class to handle all interactions with the Entropy SDK.
+ * The main class to handle all interactions within the Entropy SDK.
  */
 export default class Entropy {
-  /** A promise that resolves once the cryptographic library has been loaded. */
+  /** A promise that resolves once all internal setup has been successfully completed. */
   ready: Promise<boolean>
+
+  /* Accessor for ... TODO: */
   registrationManager: RegistrationManager
+
+  /* Accessor for ... TODO: */
   programs: ProgramManager
+
+  /* Accessor for the SignatureRequestManager.
+   * Generally you will use entropy.sign or entropy.signWithAdapter
+   *
+   */
   signingManager: SignatureRequestManager
+
+  /** Accessor for the keyring passed at instantiation */
   keyring: Keyring
+
+  /** (Advanced) Accessor for the raw subtate API. */
   substrate: ApiPromise
 
   /**
-   * Initializes an instance of the Entropy class.
+   * @param {EntropyOpts} opts
    *
-   * @param {EntropyOpts} opts - The configuration options for the Entropy instance.
+   * @example
+   * ```ts
+   * import { Entropy, wasmGlobalsReady } from '@entropyxyz/sdk'
+   * import { Keyring } from '@entropyxyz/sdk/keys'
+   *
+   * async function main () {
+   *   const keyring = new Keyring({ seed })
+   *   const entropy = new Entropy({ keyring })
+   *
+   *   await wasmGlobalsReady()
+   *   await entropy.ready
+   * }
+   *
+   * main()
+   * ```
    */
 
   constructor (opts: EntropyOpts) {
@@ -114,6 +143,7 @@ export default class Entropy {
     const admin = this.keyring.getLazyLoadAccountProxy(ChildKey.registration)
     const deviceKey = this.keyring.getLazyLoadAccountProxy(ChildKey.deviceKey)
     const vk = admin.verifyingKeys || []
+
     // HACK: these assignments trigger important `account-update` flows via the Proxy 
     admin.verifyingKeys = [...vk, verifyingKey]
     deviceKey.verifyingKeys = [verifyingKey, ...vk]
@@ -179,6 +209,10 @@ export default class Entropy {
     return this.signingManager.sign(params)
   }
 
+  /**
+   * Shuts the Entropy SDK down gracefully.
+   * Closes substrate connections for you.
+   */
   async close () {
     if (!this.substrate) return
 

src/keys/index.ts

@@ -20,56 +20,72 @@ const ACCOUNTS = Object.keys(ChildKey)
  */
 export default class Keyring {
   // private
-  // it's a unit8array if it comes from a mnemonic and a string if it comes from the user
-  // The seed used to generate keys, can be a Uint8Array (from mnemonic) or a string (user-provided).
+  // The seed used to generate keys. Can be a Uint8Array (from mnemonic) or a string (from seed).
   #seed: Uint8Array | string
+  // The the names of accounts used in this keyring
   #used: string[]
+
+  /** The accounts  */
   accounts: AccountsEmitter
   crypto: Crypto
 
   /**
    * Initializes a new instance of the `Keyring` class.
    *
-   * @param account - The key material and entropy account used for key generation.
+   * @param account - The key material (or account) used for key generation.
+   *
+   * @example
+   *
+   * ```ts
+   * import { Keyring } from '@entropyxyz/sdk/keys'
+   *
+   * const keyring = new Keyring({
+   *   seed: '0xbc1ede780f784bb6991a585e4f6e61522c14e1cae6ad0895fb57b9a205a8f938'
+   * })
+   *
+   * keyring.accounts.on('account-update', (fullAccount) => {
+   *   // TODO: persist this
+   * })
+   * ```
    */
 
   constructor (account: KeyMaterial) {
-    // this repersents keys that are used by the user
+    // The the names of accounts used in this keyring
     this.#used = ['admin', ChildKey.registration]
     Object.keys(account).forEach((key) => {
-      if (typeof account[key] === 'object' && account[key].userContext) {
+      if (account[key]?.userContext) {
         this.#used.push(key)
       } else if ((account as EntropyAccount).debug) {
         this.#used.push(key)
       }
     })
+
+    // set #seed
     const { seed, mnemonic } = account
     if (!seed && !mnemonic)
       throw new Error('Need at least a seed or mnemonic to create keys')
-    if (mnemonic) {
-      this.#seed = utils.seedFromMnemonic(mnemonic)
-    } else {
-      this.#seed = seed
-    }
+    this.#seed = mnemonic
+      ? utils.seedFromMnemonic(mnemonic)
+      : seed
+
+    // setup accounts
     const accountsJson = this.#formatAccounts(account)
     this.accounts = this.#createFunctionalAccounts(accountsJson)
     this.accounts.masterAccountView = accountsJson
   }
 
-  #formatAccounts (accounts: EntropyAccount): EntropyAccount {
 
+  #formatAccounts (accounts: EntropyAccount): EntropyAccount {
+    // TODO: refactor to use "account" not "accounts"
     const { seed, type, admin } = accounts
     const debug = true
     const entropyAccountsJson = {
       debug,
-      // previously was seed ? seed : utils.seedFromMnemonic(mnemonic) but this has already been derived in the constructor
-      // @frankie correct if im wrong here
       seed: this.#seed,
       type,
       admin,
     }
 
-
     Object.keys(accounts)
       .concat(ACCOUNTS)
       .forEach((key) => {

src/keys/types/json.ts

@@ -73,7 +73,7 @@ export type Mnemonic = string
 
 export type KeyMaterial =
   | (HexSeedMaterial & MnemonicSeedMaterial)
-  | EntropyAccount //HexSeedMaterial & MnemonicSeedMaterial
+  | EntropyAccount // HexSeedMaterial & MnemonicSeedMaterial
 
 /**
  * Represents key material using a hexadecimal seed.

src/registration/index.ts

@@ -6,8 +6,9 @@ import { Signer } from '../keys/types/internal'
 import { Address } from '../types/internal'
 
 export interface RegistrationParams {
+  /** initial programs associated with the user */
   programData: ProgramInstance[]
-  /** just testing this functionality, not intending to use this as the set program */
+  /** The account authorized to modify programs on behalf of the user. */
   programDeployer?: SS58Address
 }
 

tests/sign.test.ts

@@ -8,6 +8,7 @@ import {
   spinNetworkDown,
   charlieStashSeed,
   charlieSeed,
+  sleep,
 } from './testing-utils'
 
 const NETWORK_TYPE = 'two-nodes'
@@ -65,7 +66,6 @@ test('Sign: custom signatureVerifyingKey', async (t) => {
 
   /* Setup Network */
   await run('network up', spinNetworkUp(NETWORK_TYPE))
-  await sleep(process.env.GITHUB_WORKSPACE ? 30_000 : 5_000)
   t.teardown(async () => {
     // this gets called after all tests are run
     await charlieStashEntropy.close()

tsconfig.json

@@ -15,11 +15,10 @@
     "module": "Node16"
   },
   "exclude": [
-    "node_modules",
+    "dev",
     "dist",
-    "build",
-    "examples",
-    "old",
+    "docs",
+    "node_modules",
     "substrate-generated-types"
   ],
   "ts-node": {

tsup.config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from 'tsup'
 export default defineConfig((options) => {
   return {
     entry: [
-      `src/index.ts`,
+      'src/index.ts',
       'src/keys/index.ts',
       'src/keys/utils.ts',
       'src/utils/index.ts',

typedoc.config.cjs

@@ -0,0 +1,38 @@
+/** @type {import('typedoc').TypeDocOptions} */
+
+// see: https://typedoc.org/options/
+
+module.exports = {
+  // NOTE: entryPoints reflects pakcage.json "exports"
+  entryPoints: [
+    'src/index.ts',
+    'src/keys/index.ts',
+  ],
+  // entryPointStrategy: 'expand',
+
+  out: './docs',
+
+  tsconfig: './tsconfig.json',
+  excludePrivate: true,
+  // excludeInternal: true,
+  validation: {
+    notExported: true,
+    invalidLink: true,
+    notDocumented: true,
+  },
+  plugin: [
+    '@mxssfd/typedoc-theme',
+    'typedoc-plugin-rename-defaults',
+    'typedoc-plugin-merge-modules',
+    // 'typedoc-plugin-missing-exports',
+  ],
+  /* typedoc-plugin-missing-exports:*/
+  // internalModule: 'internal',
+  // placeInternalsInOwningModule: true,
+
+  /* typedoc-plugin-merge-modules: */
+  mergeModulesRenameDefaults: true,
+  mergeModulesMergeMode: 'project',
+
+  theme: 'my-theme',
+}