Skip to content

Commit 437ba02

Browse files
csr632csr632
committed
add document for "Library Documentation Tools"
1 parent 89d1510 commit 437ba02

File tree

10 files changed

+297
-11
lines changed

10 files changed

+297
-11
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ It provides many features that help developers **build a React App quickly**:
1818
- **Powerful [theme customization](https://vitejs.github.io/vite-plugin-react-pages/theme-customization)**. Vite-pages itself doesn't render any concrete DOM node. You can customize **anything** on the page with theme. It is easy to write a theme that is sharable and configurable. If you use typescript, the users of your theme will get type-check and intelliSense.
1919
- **Automatic code splitting based on pages**. Visitors don't need to download the whole app, they only load page data as needed.
2020
- **Support static site generation out of the box**. By pre-rendering your app into HTML at buildtime, users can see the content before any JS is loaded. With this feature, you can [deploy your single page apps on GitHub Pages](https://github.com/vitejs/vite-plugin-react-pages/tree/main/doc-site)(which [doesn't natively support single page apps](https://www.google.com/search?q=github+pages+single+page+apps&oq=github+pages+single+page+apps)).
21+
- **Tools for Library documentation**. Vite-pages provides [some tools](https://vitejs.github.io/vite-plugin-react-pages/library-documentation-tools) to reduce the maintenance costs for library authors and make their documents more easily to read.
2122

2223
## Getting stated
2324

‎doc-site/pages/$.mdx

+3-2
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,10 @@ It provides many features that help developers **build a React App quickly**:
2929
- **Fantastic development experience**. Start the local development server in a blink, even when you have many pages. Hot module replacement works with React and Mdx, so you can get instant feedback when you edit your code.
3030
- **Filesystem based routing**. By following a [simple filesystem routing convention](/fs-routing), It is easy to create, locate and develop pages. You don't need to worry about routing configuration. For advanced users, you can [tell vite-pages how to find page files](/advanced-fs-routing), so that vite-pages can work with any project file structure.
3131
- **Support Mdx**. You can write content with either "normal React" or [Mdx](https://mdxjs.com/). Normal Reactjs is more flexible and composable. While Mdx is more readable and easier to edit. You can choose the proper format for your task. These formats can import each other like normal esModules.
32-
- **Powerful [theme customization](/theme)**. Vite-pages itself doesn't render any concrete DOM node. You can customize **anything** on the page with theme. It is easy to write a theme that is sharable and configurable. If you use typescript, the users of your theme will get type-check and intelliSense.
32+
- **Powerful [theme customization](/theme-customization)**. Vite-pages itself doesn't render any concrete DOM node. You can customize **anything** on the page with theme. It is easy to write a theme that is sharable and configurable. If you use typescript, the users of your theme will get type-check and intelliSense.
3333
- **Automatic code splitting based on pages**. Visitors don't need to download the whole app, they only load page data as needed.
3434
- **Support static site generation out of the box**. By pre-rendering your app into HTML at buildtime, users can see the content before any JS is loaded. With this feature, you can [deploy your single page apps on GitHub Pages](https://github.com/vitejs/vite-plugin-react-pages/tree/main/doc-site)(which [doesn't natively support single page apps](https://www.google.com/search?q=github+pages+single+page+apps&oq=github+pages+single+page+apps)).
35+
- **Tools for Library documentation**. Vite-pages provides [some tools](/library-documentation-tools) to reduce the maintenance costs for library authors and make their documents more easily to read.
3536

3637
## Getting stated
3738

@@ -53,7 +54,7 @@ You can play with these demo projects in your browser, without installing anythi
5354
2. `npm install`
5455
3. `npm run dev` and play with the local dev environment.
5556
4. `npm run build`.
56-
5. `npm run ssr`. You can [disable javascript in your browser](https://developers.google.com/web/tools/chrome-devtools/javascript/disable), to verify if it can still render.
57+
5. `npm run ssr`. You can [disable javascript in your browser](https://developer.chrome.com/docs/devtools/javascript/disable/), to verify if it can still render.
5758

5859
### Read the documentation
5960

‎doc-site/pages/library-documentation-tools/demos/demo1.tsx

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/**
2+
* @title Button Demo1 Title
3+
* @description Button demo1 description
4+
* @order 1
5+
*/
6+
7+
import React from 'react'
8+
9+
const Demo1 = () => {
10+
return <button>demo1</button>
11+
}
12+
13+
export default Demo1

‎doc-site/pages/library-documentation-tools/index$.mdx

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Library Documentation Tools
3+
order: -2
4+
subGroup: advanced
5+
---
6+
7+
# Library Documentation Tools
8+
9+
Vite-pages provides some tools to reduce the maintenance costs for library authors and make their documents more easily to read.
10+
11+
> These tools are mostly for library authors.
12+
13+
## Demos
14+
15+
Demos (or stories) are the fixtures that you use when you are developing your library locally.
16+
Vite-pages allows you to render demos into your app (which can be the document of your library). Using this feature, vite-pages app can not only serve as your **local develop environment** (so that you can debug your demos and your libary code locally), but also the **document for your library** (so that the users of your library can see your demos and lean how to use it).
17+
18+
The following markdown
19+
20+
```tsx
21+
<Demo src="./demos/demo1.tsx" />
22+
```
23+
24+
which will result in:
25+
26+
<Demo src="./demos/demo1.tsx" />
27+
28+
### Using Demo API in JS files
29+
30+
In jsx page, You can import and render demos like this:
31+
32+
```tsx
33+
import demoData from '../demos/demo1.tsx?demo'
34+
import { Demo } from 'vite-pages-theme-doc'
35+
36+
export default function Page() {
37+
return <Demo {...demoData} />
38+
}
39+
```
40+
41+
## Extract Type info from Typescript code
42+
43+
Vite-pages allows can help you to extract Typescript type info and render it. With this feature, you **no loger need to manually maintain API infomation in your documents**! You can reuse your interfaces (and comments in them) from your source code! This is very conveniently for API documentation.
44+
45+
### Render Interface
46+
47+
The following markdown
48+
49+
```tsx
50+
<TsInfo src="./types.ts" name="ButtonProps" />
51+
```
52+
53+
> The `name` should be the export name of the Typescript interface.
54+
55+
will result in:
56+
57+
<TsInfo src="./types.ts" name="ButtonProps" />
58+
59+
### Render Type Alias
60+
61+
Besides interface, TsInfo API also support type alias.
62+
63+
SomeObjectLiteralType (Object Literal):
64+
<TsInfo src="./types.ts" name="SomeObjectLiteralType" />
65+
66+
SomeComplexType (Complex Type):
67+
<TsInfo src="./types.ts" name="SomeComplexType" />
68+
69+
### Using TsInfo API in JS files
70+
71+
In jsx page, You can import and render tsInfo like this:
72+
73+
```tsx
74+
import tsInfoData from './types.ts?tsInfo=ButtonProps'
75+
import { TsInfo } from 'vite-pages-theme-doc'
76+
77+
export default function Page() {
78+
return <TsInfo {...tsInfoData} />
79+
}
80+
```
81+
82+
## Render text from files
83+
84+
You can also render text from any files. So that these files can be both "code" and "documentation".
85+
86+
The following markdown
87+
88+
```tsx
89+
<FileText src="./types.ts" syntax="ts" />
90+
```
91+
92+
will result in:
93+
94+
<FileText src="./types.ts" syntax="ts" />
95+
96+
In jsx page, You can render file text like this:
97+
98+
```tsx
99+
// https://vitejs.dev/guide/assets.html#importing-asset-as-string
100+
import text from './types.ts?raw'
101+
import { FileText } from 'vite-pages-theme-doc'
102+
103+
export default function Page() {
104+
return <FileText text={text} syntax="ts" />
105+
}
106+
```
107+
108+
## Examples
109+
110+
You can checkout [template-lib](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/src/Button/README.md) as an example. (You can [view it online](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-lib?file=src%2FButton%2FREADME.md&terminal=dev) or [init this project locally](https://vitejs.github.io/vite-plugin-react-pages/))

‎doc-site/pages/library-documentation-tools/types.ts

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
import type { MyImportedTypeAlias } from './typesUtils'
2+
export type { ReExportedInterface } from './typesUtils'
3+
export type MyExportedTypeAlias = { a: number }
4+
type MyTypeAlias = { a: number }
5+
export interface MyExportedInterface {
6+
a: number
7+
}
8+
interface MyInterface {
9+
a: number
10+
}
11+
12+
/**
13+
* This is the description of the Button component's props
14+
*/
15+
export interface ButtonProps<TestGenerics extends string> extends Base {
16+
/**
17+
* the type of button
18+
* @defaultValue 'default'
19+
*/
20+
type?: 'primary' | 'default' | 'text'
21+
/**
22+
* the size of button
23+
* @defaultValue 'middle'
24+
*/
25+
size?: 'large' | 'middle' | 'small' | TestGenerics
26+
/**
27+
* loading state of button
28+
* @defaultValue false
29+
*/
30+
loading?: boolean
31+
/**
32+
* click handler
33+
*/
34+
onClick?: (event: React.MouseEvent) => void
35+
/** test method declaration */
36+
testMethod(param: MyExportedTypeAlias): MyTypeAlias
37+
/** test required property */
38+
testRequired: boolean
39+
myExportedTypeAlias: MyExportedTypeAlias
40+
myTypeAlias: MyTypeAlias
41+
myExportedInterface: MyExportedInterface
42+
myInterface: MyInterface
43+
myImportedTypeAlias: MyImportedTypeAlias
44+
/** test call signatures */
45+
(options?: { ignorePending?: true }): Array<string | Promise<string>>
46+
(options: { ignorePending: false }): string[]
47+
/** test construct signatures */
48+
new (options: string): MyInterface
49+
new (): MyInterface
50+
}
51+
52+
interface Base {
53+
/**
54+
* children content
55+
*/
56+
children: React.ReactNode
57+
}
58+
59+
export type SomeObjectLiteralType<TestGenerics> = {
60+
/**
61+
* the type of button
62+
* @defaultValue 'default'
63+
*/
64+
type?: 'primary' | 'default' | 'text'
65+
/**
66+
* the size of button
67+
* @defaultValue 'middle'
68+
*/
69+
size?: 'large' | 'middle' | 'small' | TestGenerics
70+
/**
71+
* loading state of button
72+
* @defaultValue false
73+
*/
74+
loading?: boolean
75+
/**
76+
* click handler
77+
*/
78+
onClick?: (event: React.MouseEvent) => void
79+
/** test method declaration */
80+
testMethod(param: MyInterface): MyExportedInterface
81+
/** test required property */
82+
testRequired: boolean
83+
myExportedTypeAlias: MyExportedTypeAlias
84+
myTypeAlias: MyTypeAlias
85+
myExportedInterface: MyExportedInterface
86+
myInterface: MyInterface
87+
myImportedTypeAlias: MyImportedTypeAlias
88+
/** test call signatures */
89+
(options?: { ignorePending?: true }): Array<string | Promise<string>>
90+
(options: { ignorePending: false }): string[]
91+
/** test construct signatures */
92+
new (options: string): MyInterface
93+
new (): MyInterface
94+
}
95+
96+
/**
97+
* Description of SomeComplexType ...
98+
*/
99+
export type SomeComplexType = 0 | 1 | 'a' | 'b' | { key: string }

‎doc-site/pages/library-documentation-tools/typesUtils.ts

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
export type MyImportedTypeAlias = { b: string }
2+
/**
3+
* Comment for MyImportedInterface...
4+
*/
5+
export type ReExportedInterface = {
6+
/** Comment for MyImportedInterface.prop1 */
7+
prop1: MyImportedTypeAlias
8+
}

‎packages/create-project/template-lib/src/Button/README.md

+10-2
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,21 @@ This is a **markdown** document of the `Button` component.
99

1010
You can put this page in a subGroup of the side menu using `staticData.subGroup`.
1111

12+
---
13+
14+
Here are some examples of [library documentation tools](https://vitejs.github.io/vite-plugin-react-pages/library-documentation-tools).
15+
1216
## Demos
1317

14-
You can import demos like this:
18+
The following markdown
1519

20+
```tsx
1621
<Demo src="./demos/demo1.tsx" />
22+
```
1723

18-
<Demo src="./demos/demo2.tsx" />
24+
which will result in:
25+
26+
<Demo src="./demos/demo1.tsx" />
1927

2028
## Extract Type info from Typescript code
2129

‎packages/create-project/template-lib/src/Button/types.ts

+35-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
import type { MyImportedTypeAlias } from './typesUtils'
2+
export type { ReExportedInterface } from './typesUtils'
3+
export type MyExportedTypeAlias = { a: number }
4+
type MyTypeAlias = { a: number }
5+
export interface MyExportedInterface {
6+
a: number
7+
}
8+
interface MyInterface {
9+
a: number
10+
}
11+
112
/**
213
* This is the description of the Button component's props
314
*/
@@ -22,9 +33,20 @@ export interface ButtonProps<TestGenerics extends string> extends Base {
2233
*/
2334
onClick?: (event: React.MouseEvent) => void
2435
/** test method declaration */
25-
testMethod(param: string): void
36+
testMethod(param: MyExportedTypeAlias): MyTypeAlias
2637
/** test required property */
2738
testRequired: boolean
39+
myExportedTypeAlias: MyExportedTypeAlias
40+
myTypeAlias: MyTypeAlias
41+
myExportedInterface: MyExportedInterface
42+
myInterface: MyInterface
43+
myImportedTypeAlias: MyImportedTypeAlias
44+
/** test call signatures */
45+
(options?: { ignorePending?: true }): Array<string | Promise<string>>
46+
(options: { ignorePending: false }): string[]
47+
/** test construct signatures */
48+
new (options: string): MyInterface
49+
new (): MyInterface
2850
}
2951

3052
interface Base {
@@ -55,9 +77,20 @@ export type SomeObjectLiteralType<TestGenerics> = {
5577
*/
5678
onClick?: (event: React.MouseEvent) => void
5779
/** test method declaration */
58-
testMethod(param: string): void
80+
testMethod(param: MyInterface): MyExportedInterface
5981
/** test required property */
6082
testRequired: boolean
83+
myExportedTypeAlias: MyExportedTypeAlias
84+
myTypeAlias: MyTypeAlias
85+
myExportedInterface: MyExportedInterface
86+
myInterface: MyInterface
87+
myImportedTypeAlias: MyImportedTypeAlias
88+
/** test call signatures */
89+
(options?: { ignorePending?: true }): Array<string | Promise<string>>
90+
(options: { ignorePending: false }): string[]
91+
/** test construct signatures */
92+
new (options: string): MyInterface
93+
new (): MyInterface
6194
}
6295

6396
/**

‎packages/create-project/template-lib/src/Button/typesUtils.ts

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
export type MyImportedTypeAlias = { b: string }
2+
/**
3+
* Comment for MyImportedInterface...
4+
*/
5+
export type ReExportedInterface = {
6+
/** Comment for MyImportedInterface.prop1 */
7+
prop1: MyImportedTypeAlias
8+
}

‎packages/react-pages/README.md

+10-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# 📘 vite-plugin-react-page
1+
# 📘 vite-plugin-react-pages
22

33
<p>
44
<a href="https://www.npmjs.com/package/vite-plugin-react-pages" target="_blank" rel="noopener"><img src="https://img.shields.io/npm/v/vite-plugin-react-pages.svg" alt="npm package" /></a>
55
</p>
66

7-
[vite-plugin-react-page](https://vitejs.github.io/vite-plugin-react-pages) (vite-pages) is a React app framework powered by [vite](https://github.com/vitejs/vite). It is very suitable for:
7+
[vite-plugin-react-pages](https://vitejs.github.io/vite-plugin-react-pages) (vite-pages) is a React app framework powered by [vite](https://github.com/vitejs/vite). It is very suitable for:
88

99
- blog site
1010
- documentation site for your library or product
@@ -18,12 +18,17 @@ It provides many features that help developers **build a React App quickly**:
1818
- **Powerful [theme customization](https://vitejs.github.io/vite-plugin-react-pages/theme-customization)**. Vite-pages itself doesn't render any concrete DOM node. You can customize **anything** on the page with theme. It is easy to write a theme that is sharable and configurable. If you use typescript, the users of your theme will get type-check and intelliSense.
1919
- **Automatic code splitting based on pages**. Visitors don't need to download the whole app, they only load page data as needed.
2020
- **Support static site generation out of the box**. By pre-rendering your app into HTML at buildtime, users can see the content before any JS is loaded. With this feature, you can [deploy your single page apps on GitHub Pages](https://github.com/vitejs/vite-plugin-react-pages/tree/main/doc-site)(which [doesn't natively support single page apps](https://www.google.com/search?q=github+pages+single+page+apps&oq=github+pages+single+page+apps)).
21+
- **Tools for Library documentation**. Vite-pages provides [some tools](https://vitejs.github.io/vite-plugin-react-pages/library-documentation-tools) to reduce the maintenance costs for library authors and make their documents more easily to read.
2122

2223
## Getting stated
2324

24-
### Play with demo projects in your browser
25+
### Try it online on StackBlitz
2526

26-
Thanks to [StackBlitz WebContainers](https://blog.stackblitz.com/posts/introducing-webcontainers/), you can run vite-pages projects entirely in your browser! Checkout [vite-pages app demo](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-app?file=README.md&terminal=dev) or [vite-pages library demo](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-lib?file=README.md&terminal=dev).
27+
You can play with these demo projects in your browser, without installing anything on your machine.
28+
29+
- [app demo](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-app?file=README.md&terminal=dev)
30+
- [library demo](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-lib?file=README.md&terminal=dev)
31+
- [library monorepo demo](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-lib-monorepo?file=README.md&terminal=dev)
2732

2833
### Initialize a demo project locally
2934

@@ -35,7 +40,7 @@ Thanks to [StackBlitz WebContainers](https://blog.stackblitz.com/posts/introduci
3540
2. `npm install`
3641
3. `npm run dev` and play with the local dev environment.
3742
4. `npm run build`.
38-
5. `npm run ssr`. You can [disable javascript in your browser](https://developers.google.com/web/tools/chrome-devtools/javascript/disable), to verify if it can still render.
43+
5. `npm run ssr`. You can [disable javascript in your browser](https://developer.chrome.com/docs/devtools/javascript/disable/), to verify if it can still render.
3944

4045
### Read the documentation
4146

0 commit comments

Comments
 (0)