Removed the automatically generated docs
I tried to generate the API section of the docs automatically from tsdoc comments. That failed for the follwing reasons: 1. It has been difficult to configure the layout of the API docs, such as, what information to show, how to sort the information, etc. I kept getting less relevant parts of the API show up before the more important parts. I would have had to write a plugin/theme for typedoc to fix that, which doesn't seem worth the effort. 2. The generated docs don't seem to be nearly as useful as the docs shown in the editor. It's just easier to browse the API in an IDE than on a static website. 3. Docs must have a narrative (we're trying to walk the user through the library) which goes against the unordered nature of automatically generated docs.
This commit is contained in:
Aria Minaei
parent
e201eeee5b
commit
f24e2b96d5
17 changed files with 67 additions and 2960 deletions
|
|
@ -1,33 +0,0 @@
|
|||
;(async function () {
|
||||
// better quote function from https://github.com/google/zx/pull/167
|
||||
$.quote = function quote(arg) {
|
||||
return 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 watch = argv.watch === true
|
||||
|
||||
await Promise.all(
|
||||
['core', 'studio'].map(
|
||||
(which) =>
|
||||
$`typedoc ${
|
||||
watch ? '--watch ' : ''
|
||||
} --out docs/api/${which} --name "@theatre/${which}" --tsconfig theatre/tsconfig.json --excludeInternal --sort source-order --readme none --hideBreadcrumbs true --categorizeByGroup false --defaultCategory "Main APIs" --hideInPageTOC true theatre/${which}/src/index.ts`,
|
||||
),
|
||||
)
|
||||
})()
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
<template>
|
||||
<span class="wrapper">
|
||||
<span class="chosen-platform">{{isMac ? 'mac' : 'pc'}}</span>
|
||||
{{textForChosenPlatform}}
|
||||
</span>
|
||||
</template>
|
||||
|
||||
<script lang="ts">
|
||||
import Vue from "vue";
|
||||
export default Vue.extend({
|
||||
props: {
|
||||
mac: String,
|
||||
pc: String
|
||||
},
|
||||
beforeMount() {},
|
||||
computed: {
|
||||
textForChosenPlatform() {
|
||||
return this.isMac ? this.mac : this.pc;
|
||||
}
|
||||
},
|
||||
data(opts) {
|
||||
const isMac = true;
|
||||
return { isMac };
|
||||
}
|
||||
});
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.wrapper {
|
||||
background: #f3f3f3;
|
||||
padding: 0 5px;
|
||||
position: relative;
|
||||
}
|
||||
|
||||
.chosen-platform {
|
||||
font-size: 0.7em;
|
||||
font-variant: small-caps;
|
||||
}
|
||||
</style>
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
<!-- Creates a <video /> with an aria-described-by attribute for better a11y.
|
||||
Example:
|
||||
<VideoWtihDescription src="/path/from/.vuepress/plublic/file.mp4">Description (this must be in one line, otherwise parser will reak) </VideoWithDescription>
|
||||
-->
|
||||
<template>
|
||||
<div>
|
||||
<video width="100%" controls v-bind:src="src" v-bind:aria-describedby="descriptorId"/>
|
||||
<div v-bind:id="descriptorId" style="display: none;" aria-hidden="true">
|
||||
<slot/>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts">
|
||||
import Vue from "vue";
|
||||
export default Vue.extend({
|
||||
props: {
|
||||
src: String
|
||||
},
|
||||
computed: {
|
||||
descriptorId() {
|
||||
return (
|
||||
"aria-description-video--" +
|
||||
this.src.replace(/[^a-zA-Z0-9]{1}/g, "-").toLowerCase()
|
||||
);
|
||||
}
|
||||
}
|
||||
});
|
||||
</script>
|
||||
|
|
@ -1,121 +0,0 @@
|
|||
const path = require('path')
|
||||
|
||||
const pathToMonorepo = path.join(__dirname, '../..')
|
||||
|
||||
module.exports = {
|
||||
title: 'Theatre.js',
|
||||
description: 'Motion graphics for the web',
|
||||
head: [['link', {rel: 'icon', href: '/public/theatrejs-logo-2x.png'}]],
|
||||
themeConfig: {
|
||||
logo: '/public/theatrejs-logo-black.svg',
|
||||
nav: [
|
||||
{
|
||||
text: 'Guide',
|
||||
link: '/',
|
||||
},
|
||||
{
|
||||
text: 'API',
|
||||
link: '/api',
|
||||
},
|
||||
{
|
||||
text: 'Older versions',
|
||||
items: [
|
||||
{
|
||||
text: '0.4 (Current)',
|
||||
link: 'https://docs.theatrejs.com',
|
||||
},
|
||||
{
|
||||
text: '0.3',
|
||||
link: 'https://github.com/ariaminaei/theatre/tree/0.3',
|
||||
},
|
||||
{
|
||||
text: '0.2',
|
||||
link: 'https://v02.docs.theatrejs.com/',
|
||||
},
|
||||
{
|
||||
text: '0.1',
|
||||
link: 'https://github.com/ariaminaei/theatre/tree/0.1',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Get in touch',
|
||||
items: [
|
||||
{
|
||||
text: 'Discord community',
|
||||
link: 'https://discord.gg/bm9f8F9Y9N',
|
||||
},
|
||||
{
|
||||
text: 'Twitter',
|
||||
link: 'https://twitter.com/theatre_js',
|
||||
},
|
||||
{
|
||||
text: 'Email',
|
||||
link: 'mailto:hello@theatrejs.com',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
{
|
||||
title: 'Guide',
|
||||
children: ['/getting-started'],
|
||||
},
|
||||
{
|
||||
title: 'API',
|
||||
path: '/api',
|
||||
sidebarDepth: 2,
|
||||
children: [
|
||||
{
|
||||
title: '@theatre/core',
|
||||
path: '/api/core/',
|
||||
children: [
|
||||
{
|
||||
title: 'Main exports',
|
||||
path: '/api/core/',
|
||||
},
|
||||
{
|
||||
title: 'types',
|
||||
path: '/api/core/modules/types',
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
title: '@theatre/studio',
|
||||
path: '/api/studio/',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Support',
|
||||
children: ['/support', '/faq'],
|
||||
},
|
||||
],
|
||||
lastUpdated: 'Last Updated',
|
||||
|
||||
repo: 'ariaminaei/theatre',
|
||||
docsRepo: 'ariaminaei/theatre-docs',
|
||||
docsDir: 'docs',
|
||||
docsBranch: 'main',
|
||||
editLinks: true,
|
||||
editLinkText: 'Edit this page on Github',
|
||||
},
|
||||
plugins: [
|
||||
// ...['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,
|
||||
// },
|
||||
// ]),
|
||||
],
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 8 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 18 KiB |
|
|
@ -1,22 +0,0 @@
|
|||
.content
|
||||
font-size 15px !important
|
||||
|
||||
.site-name
|
||||
display: none !important
|
||||
|
||||
.logo
|
||||
height: 1.8rem !important
|
||||
vertical-align: middle !important
|
||||
|
||||
.content a > code
|
||||
background-color rgba(86, 155, 45, 0.13)
|
||||
|
||||
.sidebar a.sidebar-link
|
||||
font-size 15px !important
|
||||
font-weight normal !important
|
||||
|
||||
.sidebar a.sidebar-link.active
|
||||
font-weight bold !important
|
||||
|
||||
.sidebar > .sidebar-links > li:not(:first-child)
|
||||
margin-top 0.25rem !important
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
---
|
||||
title: Theatre.js
|
||||
next: ./getting-started.md
|
||||
---
|
||||
|
||||
# Theatre.js
|
||||
|
||||
Theatre.js is an animation library for high-fidelity motion graphics. It is designed to help you express detailed animation, enabling you to create intricate movement, and convey nuance.
|
||||
|
||||
Theatre can be used both programmatically and visually:
|
||||
|
||||
TODO (a simple gif)
|
||||
|
||||
Theatre supports all frontend stacks. You can use it to animate DOM elements, THREE.js objects, or any JavaScript variable.
|
||||
|
||||
1
docs/api/.gitignore
vendored
1
docs/api/.gitignore
vendored
|
|
@ -1 +0,0 @@
|
|||
*/*
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
---
|
||||
title: API
|
||||
---
|
||||
|
||||
# API
|
||||
|
||||
* [`@theatre/core`](./core)
|
||||
* [`@theatre/studio`](./studio)
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# F.A.Q
|
||||
|
||||
TODO
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
---
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
# Getting started
|
||||
|
||||
|
||||
## Install Theatre
|
||||
|
||||
Add `@theatre/core` as a dependency via npm or yarn.
|
||||
|
||||
```bash
|
||||
$ npm install --save @theatre/core
|
||||
```
|
||||
|
||||
Then add `@theatre/studio` as a dev dependency since we only need it during development.
|
||||
|
||||
```bash
|
||||
$ npm install --save-dev @theatre/studio
|
||||
```
|
||||
|
||||
## Import Theatre
|
||||
|
||||
```javascript
|
||||
// import both core and studio (we can remove studio from the production bundle later)
|
||||
import {getProject} from '@theatre/core'
|
||||
import studio from '@theatre/studio'
|
||||
|
||||
// initialize the studio so the editing tools will show up on the screen
|
||||
studio.initialize()
|
||||
|
||||
// create our first project
|
||||
const myProject = getProject('My first project')
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
Under construction
|
||||
|
||||
TODO
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Community and Support
|
||||
|
||||
Join us on [Discord](https://discord.gg/bm9f8F9Y9N) or write us an [email](mailto:hello@theatrejs.com).
|
||||
11
package.json
11
package.json
|
|
@ -13,10 +13,7 @@
|
|||
"test": "jest",
|
||||
"postinstall": "husky install",
|
||||
"deploy": "zx devEnv/deploy.mjs",
|
||||
"lint:all": "eslint . --ext ts,tsx --ignore-path=.gitignore --rulesdir ./devEnv/eslint/rules",
|
||||
"docs:api": "zx devEnv/api-docs.mjs",
|
||||
"docs:dev": "vuepress dev docs",
|
||||
"docs:build": "vuepress build docs"
|
||||
"lint:all": "eslint . --ext ts,tsx --ignore-path=.gitignore --rulesdir ./devEnv/eslint/rules"
|
||||
},
|
||||
"lint-staged": {
|
||||
"**/*.(t|j)s?(x)": [
|
||||
|
|
@ -50,10 +47,6 @@
|
|||
"zx": "^2.0.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"node-gyp": "^8.1.0",
|
||||
"typedoc": "^0.21.9",
|
||||
"typedoc-plugin-markdown": "^3.10.4",
|
||||
"vuepress": "^1.8.2",
|
||||
"vuepress-plugin-typedoc": "^0.8.2"
|
||||
"node-gyp": "^8.1.0"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue