From 3c3e0a23691ea8e1323a91b2c2ca4c34b3cb9e4f Mon Sep 17 00:00:00 2001 From: Aria Minaei Date: Thu, 29 Sep 2022 14:06:43 +0200 Subject: [PATCH] Fix links to the docs repo --- CONTRIBUTING.md | 23 +------ contributing/api-docs.md | 120 ------------------------------------- package.json | 1 - scripts/build-api-docs.mjs | 82 ------------------------- 4 files changed, 3 insertions(+), 223 deletions(-) delete mode 100644 contributing/api-docs.md delete mode 100644 scripts/build-api-docs.mjs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 870420b..cabfc21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -152,20 +152,6 @@ $ yarn release x.y.z-dev.w # npm publish version x.y.z-dev.w and tag it as "dev" $ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc" ``` -### Generating API docs - -We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/) -to generate API docs in markdown. We put the markdown files in the -[theatre-docs](https://github.com/theatre-js/theatre-docs) repo, which also -contains the tutorials and guides. - -To generate the API docs, run the `build:api-docs` from the root of the repo: - -```sh -$ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api folder and regenerate the markdown files -``` - -Learn more about api documentation [here](./contributing/api-docs.md). ## Project structure @@ -218,8 +204,6 @@ $ yarn lint:all --fix # Build all the packages $ yarn build -# Build the api documentation -$ yarn build:api-docs /path/to/theatre-docs/docs/api/ ``` > Yarn passes all extra parameters to the internal scripts. So, for example, if @@ -232,9 +216,8 @@ can explore the API if your editor is configured to display TSDoc comments. Other references -- [Documentation: https://docs.theatrejs.com](https://docs.theatrejs.com/getting-started/) -- [API docs: https://docs.theatrejs.com/api/](https://docs.theatrejs.com/api/) -- [Video: Theatre.js Crash Course](https://www.youtube.com/watch?v=icR9EIS1q34) +- [Documentation: https://www.theatrejs.com/docs](https://www.theatrejs.com/docs) +- [API docs: https://www.theatrejs.com/docs/latest/api](https://www.theatrejs.com/docs/latest/api) ## What to contribute @@ -243,7 +226,7 @@ You can contribute with: - Bug fixes - Feature suggestions - Features implementations -- [Documentation](https://github.com/theatre-js/theatre-docs/) (or write/record +- [Documentation](https://github.com/theatre-js/website/) (or write/record tutorials of your own which we'll showcase) - Create examples projects for your own particular dev stack (eg. using Pixie/Vue/THREE.js/Babylon/etc) diff --git a/contributing/api-docs.md b/contributing/api-docs.md deleted file mode 100644 index 5334220..0000000 --- a/contributing/api-docs.md +++ /dev/null @@ -1,120 +0,0 @@ -# Writing API docs - -We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/) -to generate API docs in markdown. We put the markdown files in the -[theatre-docs](https://github.com/theatre-js/theatre-docs/) repo, which also -contains the tutorials and guides. - -To generate the API docs, run the `build:api-docs` from the root of the repo: - -```sh -$ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api folder and regenerate the markdown files -``` - -## JSDoc/TSDoc gotchas - -We are using TSDoc for documentation generation, IDEs use JSDoc for tooltips. -TSDoc and JSDoc have subtle differences. We need to optimize for both. - -Most users will read our documentation inside their IDEs. - -### `@example` - -IDEs automatically wrap example sections in ` ``` ` if they aren't already -wrapped by you. This means you can't use non-code explanations in example -sections, like TSDoc examples do. - -This will be formatted incorrectly: - -````ts -/** - * Adds two numbers together. - * @example - * Here's a simple example: - * ``` - * // Prints "2": - * console.log(add(1,1)); - * ``` - * @example - * Here's an example with negative numbers: - * ``` - * // Prints "0": - * console.log(add(1,-1)); - * ``` - */ -export function add(x: number, y: number): number {} -```` - -Some IDEs have problems with having multiple example sections in the same JSDoc -comment. - -WebStorm doesn’t highlight examples if you wrap them in ` ``` `. - -api-documenter doesn’t highlight examples if you don't wrap them in ` ``` `. - -### Guidelines - -- Only use one `@example` section -- Use a single code block in it, no explanations -- Wrap the code block in ` ```ts ... ``` ` (the `ts` modifier is important, - api-documenter copies the `@example` section verbatim, and our documentation - page might not highlight the vanilla ` ``` ` sections) -- If you need to explain the code, use code comments - -#### `@typeParam` - -api-documenter doesn’t generate documentation for it, but IDEs might display it -even if they don't have bespoke support for it. - -#### `@link` - -While in JSDoc you can specify paths relative to the current declaration, TSDoc -requires everything to be specified relative to the entry point. That is, if -`bar` is a member of `Foo`, and `Foo` is exported in the entry, you need to -refer to `bar` as `Foo.bar`, even inside `Foo`. - -JSDoc allows separating the link text from the link either with a space or using -`|`. TSDoc only supports `|`, _and_ you mustn’t have spaces around it. So for -example `{@link MyClass | go here}` would be rendered incorrectly, whereas -`{@link MyClass|go here}` would be correct. - -#### `@param` - -api-documenter won’t render the documentation for object properties, but -document them anyway, IDEs do. - -Since documentation is only rendered for the object and not for its properties, -make sure to include examples for these properties. - -#### `@see` - -While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc -requires an explicit `{@link}` tag tag to make hyperlinks. - -**Incorrect ❌** - -```ts -/** - * Parses a string containing a Uniform Resource Locator (URL). - - * @see ParsedUrl - - * @param url - the string to be parsed - * @returns the parsed result - */ -function parseURL(url: string): ParsedUrl -``` - -**Correct ✅** - -```ts -/** - * Parses a string containing a Uniform Resource Locator (URL). - - * @see {@link ParsedUrl} - - * @param url - The string to be parsed - * @returns The parsed result - */ -function parseURL(url: string): ParsedUrl -``` diff --git a/package.json b/package.json index e821239..ab95361 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,6 @@ "test": "jest", "postinstall": "husky install", "release": "zx scripts/release.mjs", - "build:api-docs": "zx scripts/build-api-docs.mjs", "lint:all": "eslint . --ext ts,tsx --ignore-path=.gitignore --rulesdir ./devEnv/eslint/rules" }, "lint-staged": { diff --git a/scripts/build-api-docs.mjs b/scripts/build-api-docs.mjs deleted file mode 100644 index 7324af2..0000000 --- a/scripts/build-api-docs.mjs +++ /dev/null @@ -1,82 +0,0 @@ -/** - * This script generates API documentation files in the target folder. - * Usage: `$ yarn build:api-docs ` creates the .md files in . - * Example: `$ yarn build:api-docs path/to/theatre-docs/docs/api/` - * - * Usually is https://github.com/AriaMinaei/theatre-docs/tree/main/docs/api - */ -import path from 'path' -import {parse as parseJsonC} from 'jsonc-parser' -;(async function () { - // better quote function from https://github.com/google/zx/pull/167 - $.quote = function quote(arg) { - if (/^[a-z0-9/_.-]+$/i.test(arg)) { - return arg - } - return ( - `$'` + - arg - .replace(/\\/g, '\\\\') - .replace(/'/g, "\\'") - .replace(/\f/g, '\\f') - .replace(/\n/g, '\\n') - .replace(/\r/g, '\\r') - .replace(/\t/g, '\\t') - .replace(/\v/g, '\\v') - .replace(/\0/g, '\\0') + - `'` - ) - } - - 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`, - ), - ) - - /* - We replace the Pointer name with a similar-looking one so that - api-documenter generates two different pages for Pointer and pointer, instead - of overwriting one with the other. - - Apparently any non-english character, including this one will break links, - probably due to some overzealous regex. Didn't find any replacement that doesn't - change the look of the name AND doesn't break links, however the below code does - replace links too, in case we find something in the future. For now, we shouldn't - @link to the Pointer type in TSDoc comments. - */ - const replacement = 'Pointer\u200E' - - fs.writeFileSync( - './.temp/api/dataverse.api.json', - fs - .readFileSync('./.temp/api/dataverse.api.json', { - encoding: 'utf-8', - }) - .replaceAll('"name": "Pointer"', `"name": "${replacement}"`) - .replaceAll('{@link Pointer}', `{@link ${replacement}}`), - ) - - await $`api-documenter markdown --input-folder ${pathToApiJsonFiles} --output-folder ${outputPath}` -})()