Formatting changes for api docs

devEnv/api-docs.mjs

@@ -1,6 +1,7 @@
 import path from 'path'
 import {readFileSync, writeFileSync} from 'fs'
 import {keyBy} from 'lodash-es'
+import {parse as parseJsonC} from 'jsonc-parser'
 ;(async function () {
   // better quote function from https://github.com/google/zx/pull/167
   $.quote = function quote(arg) {
@@ -22,10 +23,31 @@ import {keyBy} from 'lodash-es'
     )
   }
 
+  const outputPathArg = argv._[argv._.length - 1]
+  if (outputPathArg.trim().length === 0) {
+    console.error(
+      `You must provide a path to create the markdown files in. Eg. $ yarn build:api-docs /path/to/docs-site/docs/api`,
+    )
+    process.exit(1)
+  }
+  const outputPath = path.resolve(outputPathArg)
+
+  const pathToApiJsonFiles = path.dirname(
+    path.resolve(
+      './devEnv',
+      parseJsonC(
+        fs.readFileSync('./devEnv/api-extractor-base.json', {
+          encoding: 'utf-8',
+        }),
+      ).docModel.apiJsonFilePath,
+    ),
+  )
+
   await $`yarn build:ts`
   await Promise.all(
     ['@theatre/dataverse', '@theatre/react', 'theatre'].map(
       (pkg) => $`yarn workspace ${pkg} run build:api-json`,
     ),
   )
+  await $`api-documenter markdown --input-folder ${pathToApiJsonFiles} --output-folder ${outputPath}`
 })()

devEnv/api-extractor-base.json

@@ -175,7 +175,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
      */
-    "apiJsonFilePath": "<projectFolder>/dist/<unscopedPackageName>.api.json"
+    "apiJsonFilePath": "../.temp/api/<unscopedPackageName>.api.json"
   },
 
   /**
@@ -341,7 +341,7 @@
         "logLevel": "none"
       },
       "ae-forgotten-export": {
-        "logLevel": "none"
+        "logLevel": "warning"
       }
 
       // "ae-extra-release-tag": {

package.json

@@ -31,6 +31,8 @@
     "@babel/preset-env": "^7.15.0",
     "@babel/preset-react": "^7.14.5",
     "@babel/preset-typescript": "^7.15.0",
+    "@microsoft/api-documenter": "^7.13.54",
+    "@microsoft/api-extractor": "^7.18.11",
     "@typescript-eslint/eslint-plugin": "^4.30.0",
     "@typescript-eslint/parser": "^4.30.0",
     "esbuild": "^0.12.24",
@@ -43,15 +45,12 @@
     "eslint-plugin-unused-imports": "^1.1.4",
     "husky": "^6.0.0",
     "jest": "^27.1.0",
+    "jsonc-parser": "^3.0.0",
     "lerna": "^4.0.0",
     "lint-staged": "^11.1.2",
+    "node-gyp": "^8.1.0",
     "prettier": "^2.3.2",
     "typescript": "^4.4.2",
     "zx": "^2.0.0"
-  },
-  "dependencies": {
-    "@microsoft/api-documenter": "^7.13.54",
-    "@microsoft/api-extractor": "^7.18.11",
-    "node-gyp": "^8.1.0"
   }
 }

packages/r3f/src/components/useRefAndState.ts

@@ -4,6 +4,7 @@ import {useMemo, useState} from 'react'
 /**
  * Combines useRef() and useState().
  *
+ * @example
  * Usage:
  * ```ts
  * const [ref, val] = useRefAndState<HTMLDivElement | null>(null)

theatre/core/src/propTypes/index.ts

@@ -45,6 +45,7 @@ const validateCommonOpts = (
 /**
  * A compound prop type (basically a JS object).
  *
+ * @example
  * Usage:
  * ```ts
  * // shorthand
@@ -86,6 +87,7 @@ export const compound = <Props extends IShorthandCompoundProps>(
 /**
  * A number prop type.
  *
+ * @example
  * Usage
  * ```ts
  * // shorthand:
@@ -206,6 +208,7 @@ export const number = (
 /**
  * A boolean prop type
  *
+ * @example
  * Usage:
  * ```ts
  * // shorthand:
@@ -248,6 +251,7 @@ export const boolean = (
 /**
  * A string prop type
  *
+ * @example
  * Usage:
  * ```ts
  * // shorthand:

theatre/core/src/sequences/TheatreSequence.ts

@@ -31,6 +31,7 @@ export interface ISequence {
    *
    * @returns A promise that resolves when the playback is finished, or rejects if interruped
    *
+   * @example
    * Usage:
    * ```ts
    * // plays the sequence from the current position to sequence.length
@@ -95,6 +96,7 @@ export interface ISequence {
    *
    * Learn more [here](https://docs.theatrejs.com/in-depth/#sequence-attachaudio).
    *
+   * @example
    * Usage:
    * ```ts
    * // Loads and decodes audio from the URL and then attaches it to the sequence
@@ -116,6 +118,7 @@ export interface ISequence {
    * optimal user experience. It is better to provide a button or some other UI element
    * to communicate to the user that they have to initiate the animation.
    *
+   * @example
    * Example:
    * ```ts
    * // html: <button id="#start">start</button>
@@ -154,6 +157,7 @@ export interface ISequence {
      * This is an intermediate GainNode that Theatre feeds its audio to. It is by default
      * connected to destinationNode, but you can disconnect the gainNode and feed it to your own graph.
      *
+     * @example
      * For example:
      * ```ts
      * const {gainNode, audioContext} = await sequence.attachAudio({source: '/audio.mp3'})

theatre/core/src/sheetObjects/TheatreSheetObject.ts

@@ -26,6 +26,7 @@ export interface ISheetObject<Props extends IShorthandCompoundProps = {}> {
   /**
    * The current values of the props.
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("obj", {x: 0})
@@ -61,6 +62,7 @@ export interface ISheetObject<Props extends IShorthandCompoundProps = {}> {
    *
    * @returns an Unsubscribe function
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("Box", {position: {x: 0, y: 0}})
@@ -81,7 +83,7 @@ export interface ISheetObject<Props extends IShorthandCompoundProps = {}> {
    * values defined in the prop types, but would itself be overridden if the user
    * overrides it in the UI with a static or animated value.
    *
-   *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("obj", {position: {x: 0, y: 0}})

theatre/core/src/sheets/TheatreSheet.ts

@@ -45,6 +45,7 @@ export interface ISheet {
    *
    * @returns An Object
    *
+   * @example
    * Usage:
    * ```ts
    * // Create an object named "a unique key" with no props

theatre/shared/src/utils/addresses.ts

@@ -14,6 +14,7 @@ export interface ProjectAddress {
 /**
  * Represents the address to a specific instance of a Sheet
  *
+ * @example
  * ```ts
  * const sheet = project.sheet('a sheet', 'some instance id')
  * sheet.address.sheetId === 'a sheet'
@@ -44,6 +45,7 @@ export interface SheetObjectAddress extends SheetAddress {
   /**
    * The key of the object.
    *
+   * @example
    * ```ts
    * const obj = sheet.object('foo', {})
    * obj.address.objectKey === 'foo'

theatre/studio/src/Scrub.ts

@@ -31,6 +31,10 @@ export interface IScrubApi {
    * Set the value of a prop by its pointer. If the prop is sequenced, the value
    * will be a keyframe at the current sequence position.
    *
+   * @param pointer - A Pointer, like object.props
+   * @param value - The value to override the existing value. This is treated as a deep partial value.
+   *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("box", {x: 0, y: 0})
@@ -45,8 +49,6 @@ export interface IScrubApi {
    *   set(obj.props.z, 10)
    * })
    * ```
-   * @param pointer - A Pointer, like object.props
-   * @param value - The value to override the existing value. This is treated as a deep partial value.
    */
   set<T>(pointer: Pointer<T>, value: T): void
 }
@@ -67,6 +69,7 @@ export interface IScrub {
    * Note that running `scrub.capture()` multiple times means all the older
    * calls of `scrub.capture()` will be reset.
    *
+   * @example
    * Usage:
    * ```ts
    * scrub.capture(({set}) => {

theatre/studio/src/TheatreStudio.ts

@@ -22,6 +22,7 @@ export interface ITransactionAPI {
    * Set the value of a prop by its pointer. If the prop is sequenced, the value
    * will be a keyframe at the current sequence position.
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("box", {x: 0, y: 0})
@@ -42,6 +43,7 @@ export interface ITransactionAPI {
   /**
    * Unsets the value of a prop by its pointer.
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("box", {x: 0, y: 0})
@@ -91,15 +93,23 @@ export interface IExtension {
   id: string
   /**
    * Set this if you'd like to add a component to the global toolbar (on the top)
+   *
+   * @example
+   * TODO
    */
   globalToolbar?: {
     /**
      * A basic react component.
+     *
+     * @example
+     * TODO
      */
     component: React.ComponentType<{}>
   }
   /**
    * Introduces new pane types.
+   * @example
+   * TODO
    */
   panes?: Array<PaneClassDefinition>
 }
@@ -109,9 +119,42 @@ export type PaneInstance<ClassName extends string> = {
   instanceId: string
   definition: PaneClassDefinition
 }
+
+export interface IStudioUI {
+  /**
+   * Temporarily hides the studio
+   */
+  hide(): void
+  /**
+   * Whether the studio is currently visible or hidden
+   */
+  readonly isHidden: boolean
+  /**
+   * Makes the studio visible again.
+   */
+  restore(): void
+}
+
+export interface _StudioInitializeOpts {
+  /**
+   * The local storage key to use to persist the state.
+   *
+   * Default: "theatrejs:0.4"
+   */
+  persistenceKey?: string
+  /**
+   * Whether to persist the changes in the browser's temporary storage.
+   * It is useful to set this to false in the test environment or when debugging things.
+   *
+   * Default: true
+   */
+  usePersistentStorage?: boolean
+}
+
 /**
  * This is the public api of Theatre's studio. It is exposed through:
  *
+ * @example
  * Basic usage:
  * ```ts
  * import studio from '@theatre/studio'
@@ -119,6 +162,7 @@ export type PaneInstance<ClassName extends string> = {
  * studio.initialize()
  * ```
  *
+ * @example
  * Usage with **tree-shaking**:
  * ```ts
  * import studio from '@theatre/studio'
@@ -129,40 +173,13 @@ export type PaneInstance<ClassName extends string> = {
  * ```
  */
 export interface IStudio {
-  readonly ui: {
+  readonly ui: IStudioUI
-    /**
-     * Temporarily hides the studio
-     */
-    hide(): void
-    /**
-     * Whether the studio is currently visible or hidden
-     */
-    readonly isHidden: boolean
-    /**
-     * Makes the studio visible again.
-     */
-    restore(): void
-  }
 
   /**
    * Initializes the studio. Call it once in your index.js/index.ts module.
    * It silently ignores subsequent calls.
    */
-  initialize(opts?: {
+  initialize(opts?: _StudioInitializeOpts): void
-    /**
-     * The local storage key to use to persist the state.
-     *
-     * Default: "theatrejs:0.4"
-     */
-    persistenceKey?: string
-    /**
-     * Whether to persist the changes in the browser's temporary storage.
-     * It is useful to set this to false in the test environment or when debugging things.
-     *
-     * Default: true
-     */
-    usePersistentStorage?: boolean
-  }): void
 
   /**
    * Runs an undo-able transaction. Creates a single undo level for all
@@ -170,6 +187,7 @@ export interface IStudio {
    *
    * Will roll back if an error is thrown.
    *
+   * @example
    * Usage:
    * ```ts
    * studio.transaction(({set, unset}) => {
@@ -184,6 +202,7 @@ export interface IStudio {
    * Creates a scrub, which is just like a transaction, except you
    * can run it multiple times without creating extra undo levels.
    *
+   * @example
    * Usage:
    * ```ts
    * const scrub = studio.scrub()
@@ -214,6 +233,7 @@ export interface IStudio {
    *
    * @param threshhold - How long to wait before committing the scrub
    *
+   * @example
    * Usage:
    * ```ts
    * // Will create a new undo-level after 2 seconds have passed
@@ -246,6 +266,7 @@ export interface IStudio {
   /**
    * Sets the current selection.
    *
+   * @example
    * Usage:
    * ```ts
    * const sheet1: ISheet = ...
@@ -268,7 +289,8 @@ export interface IStudio {
   /**
    * The current selection, consisting of Sheets and Sheet Objects
    *
-   * Example:
+   * @example
+   * Usage:
    * ```ts
    * console.log(studio.selection) // => [ISheetObject, ISheet]
    * ```
@@ -309,6 +331,7 @@ export interface IStudio {
    *
    * @param projectId - same projectId as in `core.getProject(projectId)`
    *
+   * @example
    * Usage:
    * ```ts
    * const projectId = "project"

theatre/studio/src/index.ts

@@ -67,4 +67,11 @@ export {default as ToolbarSwitchSelect} from './uiComponents/toolbar/ToolbarSwit
 export {default as ToolbarIconButton} from './uiComponents/toolbar/ToolbarIconButton'
 export {default as ToolbarDropdownSelect} from './uiComponents/toolbar/ToolbarDropdownSelect'
 export type {IScrub} from '@theatre/studio/Scrub'
-export type {IStudio, IExtension} from '@theatre/studio/TheatreStudio'
+export type {
+  IStudio,
+  IExtension,
+  PaneInstance,
+  PaneClassDefinition,
+  IStudioUI,
+  _StudioInitializeOpts,
+} from '@theatre/studio/TheatreStudio'

theatre/studio/src/utils/useRefAndState.ts

@@ -4,6 +4,7 @@ import {useMemo, useState} from 'react'
 /**
  * Combines useRef() and useState().
  *
+ * @example
  * Usage:
  * ```ts
  * const [ref, val] = useRefAndState<HTMLDivElement | null>(null)

yarn.lock

@@ -22878,6 +22878,7 @@ fsevents@^1.2.7:
     eslint-plugin-unused-imports: ^1.1.4
     husky: ^6.0.0
     jest: ^27.1.0
+    jsonc-parser: ^3.0.0
     lerna: ^4.0.0
     lint-staged: ^11.1.2
     node-gyp: ^8.1.0