Skip to content

Commit 6c4198d

Browse files
jaywcjlovejaywcjlove
committed
doc: Add deveplopment document.
1 parent 4e4f556 commit 6c4198d

File tree

4 files changed

+166
-7
lines changed

4 files changed

+166
-7
lines changed

‎packages/docs/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
文档编辑预览
22
---
33

4-
我们使用 npm 来管理 uiw 文档站点的版本，使用 unpkg.com 预览。文档版本管理，是根据 unpkg 工具支持静态服务和同步 npm 包的特点，来实现这一功能的。所以我们在发布 uiw 包的同时会发布 @uiw/doc 包，版本是同步的。
4+
我们通过 [npm](https://www.npmjs.com/@uiw/react-native-doc) 来管理 UIW React Native 组件文档站点的版本，使用 [unpkg.com](https://unpkg.com/) 提供的静态资源预览和同步 npm 包的特点，，来实现[查看历史版本](https://unpkg.com/browse/@uiw/react-native-doc/)组件文档的一功能。的文档。所以我们在发布 [`@uiw/react-native`](https://www.npmjs.com/package/@uiw/react-native) 包的同时会发布 [`@uiw/react-native-doc`](https://www.npmjs.com/package/@uiw/react-native-doc) 包。
55

6-
- 通过 unpkg 预览文档网站：https://unpkg.com/@uiw/react-native-doc/doc/index.html
6+
通过 unpkg 预览文档网站：https://unpkg.com/@uiw/react-native-doc/doc/index.html
77

88
这是 v2.0.0+ 版本预览方法
99

‎website/src/component/Header/index.module.less‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,17 @@
1818
}
1919

2020
.menus {
21+
display: flex;
2122
a {
22-
border-bottom: #fff solid 2px;
23+
border-bottom: transparent solid 2px;
2324
transition: all .3s;
25+
margin-top: 5px;
2426
color: #333;
2527
}
2628
a + a {
2729
margin-left: 16px;
2830
}
29-
:global(.active) {
31+
:global(.active), a:hover {
3032
color: #1890ff;
3133
border-bottom: #1890ff solid 2px;
3234
}

‎website/src/component/Header/index.tsx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { Link, NavLink } from 'react-router-dom';
22
import pkg from '@uiw/react-native/package.json';
33
import styles from './index.module.less';
44
import { ReactComponent } from '../../assets/logo-dark.svg';
5+
import { ReactComponent as Github } from '../../assets/github.svg';
56

67
type HeaderProps = {
78
showBorder?: boolean;
@@ -30,9 +31,11 @@ export default function Header(props: HeaderProps) {
3031
<NavLink to="/docs/">文档</NavLink>
3132
<NavLink to="/components/">RN组件</NavLink>
3233
<a target="__blank" href="https://github.com/uiwjs/react-native-uiw/issues">问题反馈</a>
33-
<a target="__blank" href="https://uiwjs.github.io">Web 组件</a>
34+
<a target="__blank" href="https://uiwjs.github.io/#/components">Web 组件</a>
3435
<NavLink to="/team">团队</NavLink>
35-
<a target="__blank" href="https://github.com/uiwjs/react-native-uiw">GitHub</a>
36+
<a target="__blank" href="https://github.com/uiwjs/react-native-uiw">
37+
<Github />
38+
</a>
3639
</div>
3740
</div>
3841
</header>

‎website/src/pages/docs/development/README.md‎

Lines changed: 155 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,158 @@
33

44
这里介绍，当前组件库开发和文档编写，方便您快速介入到项目开发中。
55

6-
正在编辑中....
6+
> ⚠️ 注意：文档网站发布是监听 master 分支的更新`自动`发布到 [`gh-pages`](https://github.com/uiwjs/react-native-uiw/tree/gh-pages) 分支。
7+
> 在 package.json 中的版本号请不要随意更改，组件发布是监听 [`package.json 中的版本号`](https://github.com/uiwjs/react-native-uiw/blob/4e4f55681a71b4813a5f5fe26f4b1a859bc85a7f/.github/workflows/ci.yml#L64-L66)变更`自动`发布到 npm 上。
8+
> 这些自动化得益于 [Github Actions](https://github.com/actions) 的强力驱动。
9+
<!--rehype:style=border-left: 8px solid #ffe564;background-color: #ffe56440;padding: 12px 16px;-->
10+
11+
## 目录结构
12+
13+
```bash
14+
├── README.md -> packages/core/README.md
15+
├── package.json
16+
├── lerna.json
17+
├── tsconfig.json
18+
├── example # ----> 示例
19+
│   └── base # 基础示例
20+
├── packages # ----> 包
21+
│   ├── core # 基础组件
22+
│   │   ├── README.md
23+
│   │   ├── package.json
24+
│   │   ├── src
25+
│   │   │   ├── Avatar # 组件源码以及组件文档
26+
│   │   │   ├── ....
27+
│   │   │   └── utils
28+
│   │   └── tsconfig.json
29+
│   └── docs # 可忽略，编译后的组件文档静态文件提交到 npm 提供文档版本预览
30+
├── website # ----> 文档网站源码
31+
│   ├── README.md
32+
│   ├── package.json
33+
│   ├── public
34+
│   ├── src
35+
│   │   ├── pages # 文档示例编写在这里
36+
│   │   │   ├── components
37+
│   │   │   ├── docs
38+
│   │   │   ├── home
39+
│   │   │   └── team
40+
│   │   └── routes
41+
│   │   ├── Controller.tsx
42+
│   │   ├── history.ts
43+
│   │   ├── menus.ts # 配置菜单
44+
│   │   └── router.tsx # 配置菜单对应的页面
45+
│   └── tsconfig.json
46+
└── yarn.lock
47+
```
48+
49+
## 文档编辑预览
50+
51+
我们通过 [npm](https://www.npmjs.com/@uiw/react-native-doc) 来管理 UIW React Native 组件文档站点的版本，使用 [unpkg.com](https://unpkg.com/) 提供的静态资源预览和同步 npm 包的特点，，来实现[查看历史版本](https://unpkg.com/browse/@uiw/react-native-doc/)组件文档的一功能。的文档。所以我们在发布 [`@uiw/react-native`](https://www.npmjs.com/package/@uiw/react-native) 包的同时会发布 [`@uiw/react-native-doc`](https://www.npmjs.com/package/@uiw/react-native-doc) 包。
52+
53+
通过 unpkg 预览文档网站：https://unpkg.com/@uiw/react-native-doc/doc/index.html
54+
55+
这是 v2.0.0+ 版本预览方法
56+
57+
```shell
58+
https://unpkg.com/@uiw/react-native-doc@<包版本>/web/index.html
59+
```
60+
61+
> ⚠️ 注意：为了保持包版本同步，我们通过 [`lerna`](http://npmjs.com/lerna) 工具同时更改所有包的版本，确保组件包和文档包的版本是一致的。
62+
> 在项目根目录运行 `npm run version` 命令，即可更改所有包的版本。
63+
<!--rehype:style=border-left: 8px solid #ffe564;background-color: #ffe56440;padding: 12px 16px;-->
64+
65+
### `文档网站开发`
66+
67+
组件文档存放在组件 `packages/core`<!--rehype:style=color: #039423; background: #b7fdce;--> 包目录中，其它文档放在文档源码目录 `website/src/pages`<!--rehype:style=color: #039423; background: #b7fdce;--> 中，根据路由地址建立。
68+
69+
> 如果需要将文档网站运行起来，需要先安装依赖和编译包。
70+
<!--rehype:style=border-left: 8px solid #ffe564;background-color: #ffe56440;padding: 12px 16px;-->
71+
72+
<!--rehype:-->
73+
```bash
74+
yarn install # 安装当前依赖，和子包中的依赖
75+
yarn run build # 编译包
76+
```
77+
78+
实时监听包和文档网站本地预览
79+
80+
```bash
81+
# Step 1
82+
yarn run lib:watch # 编译输出 JS 文件
83+
# Step 2
84+
yarn run lib:watch:type # 输出类型文件 d.ts
85+
# Step 3
86+
yarn run start # 本地运行预览文档网站
87+
```
88+
89+
### `添加一个文档页面`
90+
91+
添加一个新的文档，需要新增路由、菜单、添加 `README.md` 文件。
92+
93+
#### `1. 菜单配置`
94+
95+
在 [`website/src/routes/menus.ts`](https://github.com/uiwjs/react-native-uiw/blob/4e4f55681a71b4813a5f5fe26f4b1a859bc85a7f/website/src/routes/menus.ts#L44) 中配置菜单
96+
97+
```ts
98+
export interface MenuData extends React.RefAttributes<HTMLAnchorElement>, React.AnchorHTMLAttributes<HTMLAnchorElement> {
99+
name: string;
100+
path?: string;
101+
divider?: boolean;
102+
}
103+
export const docsMenus: MenuData[] = [
104+
{ path: '/docs/getting-started', name: '快速上手' },
105+
{ divider: true, name: "环境安装" },
106+
{ path: '/docs/environment-setup/ios', name: 'iOS 环境安装' },
107+
...
108+
{ divider: true, name: "其它" },
109+
{ path: '/docs/development', name: '参与组件/文档开发' },
110+
{ href: 'https://github.com/uiwjs/react-native-uiw/releases', target: '_blank', name: '更新日志' },
111+
]
112+
export const componentMenus: MenuData[] = [ .... ]
113+
```
114+
115+
#### `2. 新增路由`
116+
117+
在 [`website/src/routes/router.tsx`](https://github.com/uiwjs/react-native-uiw/blob/4e4f55681a71b4813a5f5fe26f4b1a859bc85a7f/website/src/routes/router.tsx#L39-L41) 中加载 Markdown 以及相关文件
118+
119+
```ts
120+
export const getRouterData = {
121+
'/': {
122+
component: dynamicWrapper([], () => import('../layouts/BasicLayout')),
123+
},
124+
'/docs/getting-started': {
125+
component: dynamicWrapper([], () => import('../pages/docs/getting-started')),
126+
},
127+
....
128+
}
129+
```
130+
131+
#### `3. 新增 Markdown 文件`
132+
133+
```bash
134+
├── pages
135+
│   ├── components
136+
│   ├── docs
137+
│   │   ├── getting-started
138+
│   │   │   ├── README.md # 添加 README.md 文档
139+
│   │   │   └── index.tsx # 添加加载 README.md JS 文件
140+
```
141+
142+
添加 `website/src/pages/docs/getting-started/README.md` 和 `website/src/pages/docs/getting-started/index.tsx`
143+
144+
```tsx
145+
import Markdown, { importAll } from '../../../component/Markdown';
146+
147+
export default class Page extends Markdown {
148+
// 配置 markdown 在 GitHub 中的目录位置，用于定位编辑 Markdown
149+
path = "/website/src/pages/docs/getting-started/README.md";
150+
getMarkdown = async () => {
151+
// 这里加载指定的 Markdown 文件
152+
const md = await import('./README.md');
153+
// 也可加载组件包中的文档
154+
const mdCom = await import('@uiw/react-native/lib/Badge/README.md');
155+
// 支持 markdown 中，相对于当前 index.tsx 相对路径引入图片资源
156+
importAll((require as any).context('./', true, /\.(png|gif|jpg)$/), this.imageFiles);
157+
return md.default || md;
158+
}
159+
}
160+
```

0 commit comments

Comments
 (0)