From 5d63ce4f3eb3f6ddc92fc8b975f53b53e01f99d5 Mon Sep 17 00:00:00 2001 From: Aria Minaei Date: Sat, 4 Sep 2021 17:08:51 +0200 Subject: [PATCH] Progress on docs --- docs/.vuepress/config.js | 61 +++++++++------------ docs/api.md | 8 --- docs/api/.gitignore | 1 + docs/api/README.md | 8 +++ theatre/core/src/coreExports.ts | 2 +- theatre/core/src/index.ts | 6 ++ theatre/core/src/projects/TheatreProject.ts | 26 +++++++-- 7 files changed, 63 insertions(+), 49 deletions(-) delete mode 100644 docs/api.md create mode 100644 docs/api/.gitignore create mode 100644 docs/api/README.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c8c8668..9431549 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -56,11 +56,20 @@ module.exports = { ], }, ], - // sidebarDepth: 4, sidebar: [ + { + title: 'Guide', + children: ['/getting-started'], + }, { title: 'API', - path: '/api/', + path: '/api', + // sidebarDepth: 2, + children: ['/api/core/', '/api/studio/'], + }, + { + title: 'Support', + children: ['/support', '/faq'], }, ], lastUpdated: 'Last Updated', @@ -73,39 +82,19 @@ module.exports = { editLinkText: 'Edit this page on Github', }, plugins: [ - [ - 'vuepress-plugin-typedoc', - { - entryPoints: [ - path.join(pathToMonorepo, './theatre/core/dist/index.d.ts'), - ], - tsconfig: path.join(pathToMonorepo, './theatre/tsconfig.json'), - out: 'api/core', - // sidebar: { - // fullNames: true, - // parentCategory: 'api', - // }, - readme: 'none', - hideInPageTOC: true, - categorizeByGroup: false, - }, - ], - // [ - // 'vuepress-plugin-typedoc', - // { - // entryPoints: [ - // path.join(pathToMonorepo, './theatre/studio/src/index.ts'), - // ], - // tsconfig: path.join(pathToMonorepo, './theatre/tsconfig.json'), - // out: 'api/studio', - // // sidebar: { - // // fullNames: true, - // // parentCategory: 'api', - // // }, - // readme: 'none', - // hideInPageTOC: true, - // categorizeByGroup: false, - // }, - // ], + // ...['core', 'studio'].map((which) => [ + // 'vuepress-plugin-typedoc', + // { + // entryPoints: [ + // path.join(pathToMonorepo, `./theatre/${which}/src/index.ts`), + // ], + // tsconfig: path.join(pathToMonorepo, `./theatre/tsconfig.json`), + // out: `api/${which}`, + // sidebar: null, + // readme: `none`, + // // hideInPageTOC: true, + // // categorizeByGroup: false, + // }, + // ]), ], } diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index da92f13..0000000 --- a/docs/api.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: API ---- - -# API - -* [`@theatre/core`](./api/core) -* [`@theatre/studio`](./api/studio) \ No newline at end of file diff --git a/docs/api/.gitignore b/docs/api/.gitignore new file mode 100644 index 0000000..df3359d --- /dev/null +++ b/docs/api/.gitignore @@ -0,0 +1 @@ +*/* \ No newline at end of file diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 0000000..9691c69 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,8 @@ +--- +title: API +--- + +# API + +* [`@theatre/core`](./core) +* [`@theatre/studio`](./studio) \ No newline at end of file diff --git a/theatre/core/src/coreExports.ts b/theatre/core/src/coreExports.ts index a21f8e4..429ac90 100644 --- a/theatre/core/src/coreExports.ts +++ b/theatre/core/src/coreExports.ts @@ -42,7 +42,7 @@ export function getProject(id: string, config: IProjectConfig = {}): IProject { throw new Error( `You seem to have called Theatre.getProject("${id}", config) twice, with different config objects. ` + `This is disallowed because changing the config of a project on the fly can lead to hard-to-debug issues.\n\n` + - `You can fix this by either calling Theatre.getProject() once per project-id,` + + `You can fix this by either calling Theatre.getProject() once per projectId,` + ` or calling it multiple times but with the exact same config.`, ) } diff --git a/theatre/core/src/index.ts b/theatre/core/src/index.ts index 7f2ee52..e2581bd 100644 --- a/theatre/core/src/index.ts +++ b/theatre/core/src/index.ts @@ -1,3 +1,9 @@ +/** + * Theatre comes in two packages: `@theatre/core` (the library) and + * `@theatre/studio` (the editor). This package is the core library. + * + * @module \@theatre/core + */ export * from './coreExports' export type { IProject, diff --git a/theatre/core/src/projects/TheatreProject.ts b/theatre/core/src/projects/TheatreProject.ts index 967eb9d..1bfcbf8 100644 --- a/theatre/core/src/projects/TheatreProject.ts +++ b/theatre/core/src/projects/TheatreProject.ts @@ -6,19 +6,37 @@ import {validateName} from '@theatre/shared/utils/sanitizers' import {validateAndSanitiseSlashedPathOrThrow} from '@theatre/shared/utils/slashedPaths' import type {$IntentionalAny} from '@theatre/shared/utils/types' -export type IProjectConfig = Partial<{ - state: $IntentionalAny -}> +/** + * A project's config object (currently the only point of configuration is the project's state) + */ +export type IProjectConfig = { + /** + * The state of the project, as [exported](https://docs.theatrejs.com/export.html) by the studio. + */ + state?: $IntentionalAny +} +/** + * A Theatre project + */ export interface IProject { readonly type: 'Theatre_Project_PublicAPI' + /** + * If `@theatre/studio` is used, this promise would resolve when studio has loaded + * the state of the project into memory. + * + * If `@theatre/studio` is not used, this promise is already resolved. + */ readonly ready: Promise /** * Shows whether the project is ready to be used. - * Better to use IProject.ready, which is a promise that will + * Better to use {@link IProject.ready}, which is a promise that would * resolve when the project is ready. */ readonly isReady: boolean + /** + * The project's address + */ readonly address: ProjectAddress sheet(sheetId: string, instanceId?: string): ISheet }