Fix links to the docs repo
This commit is contained in:
Aria Minaei
Aria
parent
d0fdd823eb
commit
3c3e0a2369
4 changed files with 3 additions and 223 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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": {
|
||||
|
|
|
|||
|
|
@ -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}`
|
||||
})()
|
||||
Loading…
Reference in a new issue