variablelab/theatre
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Fix links to the docs repo

Browse source
This commit is contained in:
Aria Minaei 2022-09-29 14:06:43 +02:00 committed by Aria
parent d0fdd823eb
commit 3c3e0a2369
4 changed files with 3 additions and 223 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
CONTRIBUTING.md
View file

@ -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" $ 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 ## Project structure
@ -218,8 +204,6 @@ $ yarn lint:all --fix
# Build all the packages # Build all the packages
$ yarn build $ 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 > 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 Other references
- [Documentation: https://docs.theatrejs.com](https://docs.theatrejs.com/getting-started/) - [Documentation: https://www.theatrejs.com/docs](https://www.theatrejs.com/docs)
- [API docs: https://docs.theatrejs.com/api/](https://docs.theatrejs.com/api/) - [API docs: https://www.theatrejs.com/docs/latest/api](https://www.theatrejs.com/docs/latest/api)
- [Video: Theatre.js Crash Course](https://www.youtube.com/watch?v=icR9EIS1q34)
## What to contribute ## What to contribute
@ -243,7 +226,7 @@ You can contribute with:
- Bug fixes - Bug fixes
- Feature suggestions - Feature suggestions
- Features implementations - 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) tutorials of your own which we'll showcase)
- Create examples projects for your own particular dev stack (eg. using - Create examples projects for your own particular dev stack (eg. using
Pixie/Vue/THREE.js/Babylon/etc) Pixie/Vue/THREE.js/Babylon/etc)

120
contributing/api-docs.md
View file

@ -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
```

1
package.json
View file

@ -20,7 +20,6 @@
"test": "jest", "test": "jest",
"postinstall": "husky install", "postinstall": "husky install",
"release": "zx scripts/release.mjs", "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:all": "eslint . --ext ts,tsx --ignore-path=.gitignore --rulesdir ./devEnv/eslint/rules"
}, },
"lint-staged": { "lint-staged": {

82
scripts/build-api-docs.mjs
View file

@ -1,82 +0,0 @@
/**
* This script generates API documentation files in the target folder.
* Usage: `$ yarn build:api-docs <path>` creates the .md files in <path>.
* Example: `$ yarn build:api-docs path/to/theatre-docs/docs/api/`
*
* Usually <path> 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}`
})()