From 14173fde0a431d755a6aac0c25d4c8b1434f2a9c Mon Sep 17 00:00:00 2001 From: Aria Minaei Date: Mon, 4 Oct 2021 10:39:12 +0200 Subject: [PATCH] Formatting changes for api docs --- devEnv/api-docs.mjs | 22 +++++ devEnv/api-extractor-base.json | 4 +- package.json | 9 +- packages/r3f/src/components/useRefAndState.ts | 1 + theatre/core/src/propTypes/index.ts | 4 + theatre/core/src/sequences/TheatreSequence.ts | 4 + .../src/sheetObjects/TheatreSheetObject.ts | 4 +- theatre/core/src/sheets/TheatreSheet.ts | 1 + theatre/shared/src/utils/addresses.ts | 2 + theatre/studio/src/Scrub.ts | 7 +- theatre/studio/src/TheatreStudio.ts | 83 ++++++++++++------- theatre/studio/src/index.ts | 9 +- theatre/studio/src/utils/useRefAndState.ts | 1 + yarn.lock | 1 + 14 files changed, 111 insertions(+), 41 deletions(-) diff --git a/devEnv/api-docs.mjs b/devEnv/api-docs.mjs index 36ace55..53dec2f 100644 --- a/devEnv/api-docs.mjs +++ b/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}` })() diff --git a/devEnv/api-extractor-base.json b/devEnv/api-extractor-base.json index 0b1f0c3..530eb3a 100644 --- a/devEnv/api-extractor-base.json +++ b/devEnv/api-extractor-base.json @@ -175,7 +175,7 @@ * SUPPORTED TOKENS: , , * DEFAULT VALUE: "/temp/.api.json" */ - "apiJsonFilePath": "/dist/.api.json" + "apiJsonFilePath": "../.temp/api/.api.json" }, /** @@ -341,7 +341,7 @@ "logLevel": "none" }, "ae-forgotten-export": { - "logLevel": "none" + "logLevel": "warning" } // "ae-extra-release-tag": { diff --git a/package.json b/package.json index 7131ae6..46e5974 100644 --- a/package.json +++ b/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" } } diff --git a/packages/r3f/src/components/useRefAndState.ts b/packages/r3f/src/components/useRefAndState.ts index a40f12b..03f4873 100644 --- a/packages/r3f/src/components/useRefAndState.ts +++ b/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(null) diff --git a/theatre/core/src/propTypes/index.ts b/theatre/core/src/propTypes/index.ts index 3078e73..9879440 100644 --- a/theatre/core/src/propTypes/index.ts +++ b/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 = ( /** * 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: diff --git a/theatre/core/src/sequences/TheatreSequence.ts b/theatre/core/src/sequences/TheatreSequence.ts index 493327a..df5c5c1 100644 --- a/theatre/core/src/sequences/TheatreSequence.ts +++ b/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: @@ -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'}) diff --git a/theatre/core/src/sheetObjects/TheatreSheetObject.ts b/theatre/core/src/sheetObjects/TheatreSheetObject.ts index d5bb9e6..1c2e1ed 100644 --- a/theatre/core/src/sheetObjects/TheatreSheetObject.ts +++ b/theatre/core/src/sheetObjects/TheatreSheetObject.ts @@ -26,6 +26,7 @@ export interface ISheetObject { /** * The current values of the props. * + * @example * Usage: * ```ts * const obj = sheet.object("obj", {x: 0}) @@ -61,6 +62,7 @@ export interface ISheetObject { * * @returns an Unsubscribe function * + * @example * Usage: * ```ts * const obj = sheet.object("Box", {position: {x: 0, y: 0}}) @@ -81,7 +83,7 @@ export interface ISheetObject { * 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}}) diff --git a/theatre/core/src/sheets/TheatreSheet.ts b/theatre/core/src/sheets/TheatreSheet.ts index 842fe7d..f83288b 100644 --- a/theatre/core/src/sheets/TheatreSheet.ts +++ b/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 diff --git a/theatre/shared/src/utils/addresses.ts b/theatre/shared/src/utils/addresses.ts index 78952fc..8951036 100644 --- a/theatre/shared/src/utils/addresses.ts +++ b/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' diff --git a/theatre/studio/src/Scrub.ts b/theatre/studio/src/Scrub.ts index 1bb196f..071344a 100644 --- a/theatre/studio/src/Scrub.ts +++ b/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(pointer: Pointer, 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}) => { diff --git a/theatre/studio/src/TheatreStudio.ts b/theatre/studio/src/TheatreStudio.ts index b50cc5a..71d370f 100644 --- a/theatre/studio/src/TheatreStudio.ts +++ b/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 } @@ -109,9 +119,42 @@ export type PaneInstance = { 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 = { * studio.initialize() * ``` * + * @example * Usage with **tree-shaking**: * ```ts * import studio from '@theatre/studio' @@ -129,40 +173,13 @@ export type PaneInstance = { * ``` */ export interface IStudio { - readonly ui: { - /** - * Temporarily hides the studio - */ - hide(): void - /** - * Whether the studio is currently visible or hidden - */ - readonly isHidden: boolean - /** - * Makes the studio visible again. - */ - restore(): void - } + readonly ui: IStudioUI /** * Initializes the studio. Call it once in your index.js/index.ts module. * It silently ignores subsequent calls. */ - initialize(opts?: { - /** - * 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 + initialize(opts?: _StudioInitializeOpts): 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" diff --git a/theatre/studio/src/index.ts b/theatre/studio/src/index.ts index a561304..add8191 100644 --- a/theatre/studio/src/index.ts +++ b/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' diff --git a/theatre/studio/src/utils/useRefAndState.ts b/theatre/studio/src/utils/useRefAndState.ts index a40f12b..03f4873 100644 --- a/theatre/studio/src/utils/useRefAndState.ts +++ b/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(null) diff --git a/yarn.lock b/yarn.lock index 2d05b40..392ec1c 100644 --- a/yarn.lock +++ b/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