Merge pull request #1811 from vuejs/feat/docs-local-development

fgiraud · web-flow · commit f8897598bd35 · 2019-09-03T19:08:00.000-04:00
docs(dev): adding doc to local development and add more script
diff --git a/lerna.json b/lerna.json
@@ -1,5 +1,4 @@
 {
-  "lerna": "2.5.1",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "version": "1.0.3"
diff --git a/package.json b/package.json
@@ -8,8 +8,11 @@
   "description": "Minimalistic doc generator with Vue component based layout system",
   "scripts": {
     "precommit": "lint-staged",
-    "bootstrap": "yarn && lerna bootstrap && yarn tsc",
+    "bootstrap": "yarn && yarn tsc",
     "clean": "lerna clean && rm -rf node_modules",
+    "packages:list": "lerna ls -l",
+    "packages:diff": "lerna diff",
+    "packages:changed": "lerna changed",
     "boot": "node scripts/bootstrap.js",
     "remote-version": "node scripts/remote-version.js",
     "dev": "yarn tsc && yarn dev:docs",
@@ -19,11 +22,12 @@
     "view-info": "yarn tsc && yarn workspace docs view-info",
     "show-help": "yarn workspace docs show-help",
     "register-vuepress": "lerna exec --scope vuepress -- yarn link",
+    "unregister-vuepress": "lerna exec --scope vuepress -- yarn unlink",
     "lint": "eslint packages --fix --ext .js,.vue",
-    "release": "yarn --pure-lockfile && yarn tsc && node scripts/release.js",
+    "release": "yarn --pure-lockfile && yarn tsc &&  node scripts/release.js",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 2",
     "test": "node scripts/test.js",
-    "tsc": "lerna run tsc"
+    "tsc": "yarn workspace @vuepress/shared-utils tsc"
   },
   "devDependencies": {
     "@types/escape-html": "^0.0.20",
diff --git a/packages/docs/docs/.vuepress/nav/en.js b/packages/docs/docs/.vuepress/nav/en.js
@@ -1,70 +1,74 @@
 module.exports = [
   {
-    text: 'Guide',
-    link: '/guide/',
+    text: "Guide",
+    link: "/guide/"
   },
   {
-    text: 'Config Reference',
-    link: '/config/'
+    text: "Config Reference",
+    link: "/config/"
   },
   {
-    text: 'Plugin',
-    link: '/plugin/'
+    text: "Plugin",
+    link: "/plugin/"
   },
   {
-    text: 'Theme',
-    link: '/theme/'
+    text: "Theme",
+    link: "/theme/"
   },
   {
-    text: 'Learn More',
+    text: "Learn More",
     items: [
       {
-        text: 'API',
+        text: "API",
         items: [
           {
-            text: 'CLI',
-            link: '/api/cli.html'
+            text: "CLI",
+            link: "/api/cli.html"
           },
           {
-            text: 'Node',
-            link: '/api/node.html'
-          },
+            text: "Node",
+            link: "/api/node.html"
+          }
         ]
       },
       {
-        text: 'Contributing Guide',
+        text: "Contributing Guide",
         items: [
           {
-            text: 'Design Concepts',
-            link: '/miscellaneous/design-concepts.html'
+            text: "Local Development",
+            link: "/miscellaneous/local-development.html"
           },
           {
-            text: 'FAQ',
-            link: '/faq/',
+            text: "Design Concepts",
+            link: "/miscellaneous/design-concepts.html"
           },
           {
-            text: 'Glossary',
-            link: '/miscellaneous/glossary.html'
+            text: "FAQ",
+            link: "/faq/"
           },
+          {
+            text: "Glossary",
+            link: "/miscellaneous/glossary.html"
+          }
         ]
       },
       {
-        text: 'Miscellaneous',
+        text: "Miscellaneous",
         items: [
           {
-            text: 'Migrate from 0.x',
-            link: '/miscellaneous/migration-guide.html'
+            text: "Migrate from 0.x",
+            link: "/miscellaneous/migration-guide.html"
           },
           {
-            text: 'Changelog',
-            link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md'
+            text: "Changelog",
+            link: "https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md"
           }
         ]
       }
     ]
   },
   {
-    text: '0.x',
-    link: 'https://vuepress.vuejs.org/'
-  },
-]
+    text: "0.x",
+    link: "https://vuepress.vuejs.org/"
+  }
+];
diff --git a/packages/docs/docs/.vuepress/nav/zh.js b/packages/docs/docs/.vuepress/nav/zh.js
@@ -1,70 +1,74 @@
 module.exports = [
   {
-    text: '指南',
-    link: '/zh/guide/',
+    text: "指南",
+    link: "/zh/guide/"
   },
   {
-    text: '配置',
-    link: '/zh/config/'
+    text: "配置",
+    link: "/zh/config/"
   },
   {
-    text: '插件',
-    link: '/zh/plugin/'
+    text: "插件",
+    link: "/zh/plugin/"
   },
   {
-    text: '主题',
-    link: '/zh/theme/'
+    text: "主题",
+    link: "/zh/theme/"
   },
   {
-    text: '了解更多',
+    text: "了解更多",
     items: [
       {
-        text: 'API',
+        text: "API",
         items: [
           {
-            text: 'CLI',
-            link: '/zh/api/cli.html'
+            text: "CLI",
+            link: "/zh/api/cli.html"
           },
           {
-            text: 'Node',
-            link: '/zh/api/node.html'
-          },
+            text: "Node",
+            link: "/zh/api/node.html"
+          }
         ]
       },
       {
-        text: '开发指南',
+        text: "开发指南",
         items: [
           {
-            text: '设计理念',
-            link: '/zh/miscellaneous/design-concepts.html'
+            text: "Local Development",
+            link: "/miscellaneous/local-development.html"
           },
           {
-            text: 'FAQ',
-            link: '/zh/faq/',
+            text: "设计理念",
+            link: "/zh/miscellaneous/design-concepts.html"
           },
           {
-            text: '术语',
-            link: '/zh/miscellaneous/glossary.html'
+            text: "FAQ",
+            link: "/zh/faq/"
           },
+          {
+            text: "术语",
+            link: "/zh/miscellaneous/glossary.html"
+          }
         ]
       },
       {
-        text: '其他',
+        text: "其他",
         items: [
           {
-            text: '从 0.x 迁移',
-            link: '/zh/miscellaneous/migration-guide.html'
+            text: "从 0.x 迁移",
+            link: "/zh/miscellaneous/migration-guide.html"
           },
           {
-            text: 'Changelog',
-            link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md'
+            text: "Changelog",
+            link: "https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md"
           }
         ]
       }
     ]
   },
   {
-    text: '0.x',
-    link: 'https://vuepress.vuejs.org/'
-  },
-]
+    text: "0.x",
+    link: "https://vuepress.vuejs.org/"
+  }
+];
diff --git a/packages/docs/docs/miscellaneous/local-development.md b/packages/docs/docs/miscellaneous/local-development.md
@@ -0,0 +1,101 @@
+---
+sidebar: auto
+---
+
+# Local Development
+
+## Informations
+
+If you here youh may be intereset of improve core vuepress.
+
+Vuepress is using a combo with [Yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [Lerna](https://github.com/lerna/lerna).
+
+## Init packages
+
+```bash
+ yarn bootstrap // it will run and install into the root all packages subfolders
+```
+
+yarn bootstrap will use hoisting. What it mean for you ?
+
+It will regroup all dependencies in the workspace root and link all packages.
+
+to check the link you can run
+
+```bash
+    ls -la node_modules/@vuepress
+```
+
+You will all symlinks
+
+:::warning
+You have to take care to declare all dependencies inside subFolders package.json. When publish the lib if dependencie from a package is not declare it will just not work.
+:::
+
+:::warning
+There is a special package you should have a look is @vuepress/shared-utils that are in typescript.
+:::
+
+After install everything it will run `yarn tsc`. This command will tell to @vuepress/shared-utils workspace to compile his js.
+
+:::warning
+From here if you are making change inside this package you will have to
+run `yarn tsc` all the time or run in separate shell `yarn run tsc -w`. This will re run tsc at any change from shared-utils
+:::
+
+## Link
+
+Good from here you have everything ready. You need to link vuepress to your project.
+
+```bash
+yarn register-vuepress
+```
+
+You will have something like this: `success Registered "vuepress".`
+
+It will link the package vuepress from packages/vuepress. So you will have access to vuepress cli and vuepress packages.
+
+they are decalre in the `packages/vuepress/package.json`
+
+```js
+{
+"main": "index.js",
+///
+"bin": {
+    "vuepress": "cli.js"
+  }
+  ///
+}
+```
+
+Now go to your project and run `yarn link vuepress`.
+
+You should have it `success Using linked package for "vuepress".`
+
+## Unlink
+
+You may want to unlink everything. For it in the workspace root folder. Run
+
+```bash
+yarn unregister-vuepress
+```
+
+Now you can run `yarn unlink vuepress` into your project folder.
+
+If everything work properly you should have an error telling you there is no package found called vuepress, if you run `yarn link vuepress` in you project folder.
+
+## BUGS / QA
+
+You will maybe find some difficulty with link. If you encounter something like `There's already a package called "vuepress" registered`.
+You have already vuepress registered. so:
+
+- if you already link vuepress from [Link](#link). It's totally fine. If you make changes because it is symlink you dont have to re run something. You will have to rerun yarn tsc if you update shared-utils package. Nothing more
+- if you have done nothing. You have already vuepress linked somewhere. What you have to do is to delete folder where you already run `yarn link` or run `yarn unlink` inside it.
+
+## More
+
+You will have interesting commands available:
+
+- `yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme)
+- `yarn packages:changed` will tell you which package will be affect by the next lerna publish / version [More...](https://github.com/lerna/lerna/tree/master/commands/changed#readme)
+- `yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme)
diff --git a/packages/docs/docs/zh/miscellaneous/local-development.md b/packages/docs/docs/zh/miscellaneous/local-development.md
@@ -0,0 +1,5 @@
+---
+sidebar: auto
+---
+
+# need trad

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`{`
`2`		`- "lerna": "2.5.1",`
`3`	`2`	`"npmClient": "yarn",`
`4`	`3`	`"useWorkspaces": true,`
`5`	`4`	`"version": "1.0.3"`
Original file line number	Diff line number	Diff line change
`@@ -1,70 +1,74 @@`
`1`	`1`	`module.exports = [`
`2`	`2`	`{`
`3`		`- text: 'Guide',`
`4`		`- link: '/guide/',`
	`3`	`+ text: "Guide",`
	`4`	`+ link: "/guide/"`
`5`	`5`	`},`
`6`	`6`	`{`
`7`		`- text: 'Config Reference',`
`8`		`- link: '/config/'`
	`7`	`+ text: "Config Reference",`
	`8`	`+ link: "/config/"`
`9`	`9`	`},`
`10`	`10`	`{`
`11`		`- text: 'Plugin',`
`12`		`- link: '/plugin/'`
	`11`	`+ text: "Plugin",`
	`12`	`+ link: "/plugin/"`
`13`	`13`	`},`
`14`	`14`	`{`
`15`		`- text: 'Theme',`
`16`		`- link: '/theme/'`
	`15`	`+ text: "Theme",`
	`16`	`+ link: "/theme/"`
`17`	`17`	`},`
`18`	`18`	`{`
`19`		`- text: 'Learn More',`
	`19`	`+ text: "Learn More",`
`20`	`20`	`items: [`
`21`	`21`	`{`
`22`		`- text: 'API',`
	`22`	`+ text: "API",`
`23`	`23`	`items: [`
`24`	`24`	`{`
`25`		`- text: 'CLI',`
`26`		`- link: '/api/cli.html'`
	`25`	`+ text: "CLI",`
	`26`	`+ link: "/api/cli.html"`
`27`	`27`	`},`
`28`	`28`	`{`
`29`		`- text: 'Node',`
`30`		`- link: '/api/node.html'`
`31`		`- },`
	`29`	`+ text: "Node",`
	`30`	`+ link: "/api/node.html"`
	`31`	`+ }`
`32`	`32`	`]`
`33`	`33`	`},`
`34`	`34`	`{`
`35`		`- text: 'Contributing Guide',`
	`35`	`+ text: "Contributing Guide",`
`36`	`36`	`items: [`
`37`	`37`	`{`
`38`		`- text: 'Design Concepts',`
`39`		`- link: '/miscellaneous/design-concepts.html'`
	`38`	`+ text: "Local Development",`
	`39`	`+ link: "/miscellaneous/local-development.html"`
`40`	`40`	`},`
`41`	`41`	`{`
`42`		`- text: 'FAQ',`
`43`		`- link: '/faq/',`
	`42`	`+ text: "Design Concepts",`
	`43`	`+ link: "/miscellaneous/design-concepts.html"`
`44`	`44`	`},`
`45`	`45`	`{`
`46`		`- text: 'Glossary',`
`47`		`- link: '/miscellaneous/glossary.html'`
	`46`	`+ text: "FAQ",`
	`47`	`+ link: "/faq/"`
`48`	`48`	`},`
	`49`	`+ {`
	`50`	`+ text: "Glossary",`
	`51`	`+ link: "/miscellaneous/glossary.html"`
	`52`	`+ }`
`49`	`53`	`]`
`50`	`54`	`},`
`51`	`55`	`{`
`52`		`- text: 'Miscellaneous',`
	`56`	`+ text: "Miscellaneous",`
`53`	`57`	`items: [`
`54`	`58`	`{`
`55`		`- text: 'Migrate from 0.x',`
`56`		`- link: '/miscellaneous/migration-guide.html'`
	`59`	`+ text: "Migrate from 0.x",`
	`60`	`+ link: "/miscellaneous/migration-guide.html"`
`57`	`61`	`},`
`58`	`62`	`{`
`59`		`- text: 'Changelog',`
`60`		`- link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md'`
	`63`	`+ text: "Changelog",`
	`64`	`+ link: "https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md"`
`61`	`65`	`}`
`62`	`66`	`]`
`63`	`67`	`}`
`64`	`68`	`]`
`65`	`69`	`},`
`66`	`70`	`{`
`67`		`- text: '0.x',`
`68`		`- link: 'https://vuepress.vuejs.org/'`
`69`		`- },`
`70`		`-]`
	`71`	`+ text: "0.x",`
	`72`	`+ link: "https://vuepress.vuejs.org/"`
	`73`	`+ }`
	`74`	`+];`
Original file line number	Diff line number	Diff line change
`@@ -1,70 +1,74 @@`
`1`	`1`	`module.exports = [`
`2`	`2`	`{`
`3`		`- text: '指南',`
`4`		`- link: '/zh/guide/',`
	`3`	`+ text: "指南",`
	`4`	`+ link: "/zh/guide/"`
`5`	`5`	`},`
`6`	`6`	`{`
`7`		`- text: '配置',`
`8`		`- link: '/zh/config/'`
	`7`	`+ text: "配置",`
	`8`	`+ link: "/zh/config/"`
`9`	`9`	`},`
`10`	`10`	`{`
`11`		`- text: '插件',`
`12`		`- link: '/zh/plugin/'`
	`11`	`+ text: "插件",`
	`12`	`+ link: "/zh/plugin/"`
`13`	`13`	`},`
`14`	`14`	`{`
`15`		`- text: '主题',`
`16`		`- link: '/zh/theme/'`
	`15`	`+ text: "主题",`
	`16`	`+ link: "/zh/theme/"`
`17`	`17`	`},`
`18`	`18`	`{`
`19`		`- text: '了解更多',`
	`19`	`+ text: "了解更多",`
`20`	`20`	`items: [`
`21`	`21`	`{`
`22`		`- text: 'API',`
	`22`	`+ text: "API",`
`23`	`23`	`items: [`
`24`	`24`	`{`
`25`		`- text: 'CLI',`
`26`		`- link: '/zh/api/cli.html'`
	`25`	`+ text: "CLI",`
	`26`	`+ link: "/zh/api/cli.html"`
`27`	`27`	`},`
`28`	`28`	`{`
`29`		`- text: 'Node',`
`30`		`- link: '/zh/api/node.html'`
`31`		`- },`
	`29`	`+ text: "Node",`
	`30`	`+ link: "/zh/api/node.html"`
	`31`	`+ }`
`32`	`32`	`]`
`33`	`33`	`},`
`34`	`34`	`{`
`35`		`- text: '开发指南',`
	`35`	`+ text: "开发指南",`
`36`	`36`	`items: [`
`37`	`37`	`{`
`38`		`- text: '设计理念',`
`39`		`- link: '/zh/miscellaneous/design-concepts.html'`
	`38`	`+ text: "Local Development",`
	`39`	`+ link: "/miscellaneous/local-development.html"`
`40`	`40`	`},`
`41`	`41`	`{`
`42`		`- text: 'FAQ',`
`43`		`- link: '/zh/faq/',`
	`42`	`+ text: "设计理念",`
	`43`	`+ link: "/zh/miscellaneous/design-concepts.html"`
`44`	`44`	`},`
`45`	`45`	`{`
`46`		`- text: '术语',`
`47`		`- link: '/zh/miscellaneous/glossary.html'`
	`46`	`+ text: "FAQ",`
	`47`	`+ link: "/zh/faq/"`
`48`	`48`	`},`
	`49`	`+ {`
	`50`	`+ text: "术语",`
	`51`	`+ link: "/zh/miscellaneous/glossary.html"`
	`52`	`+ }`
`49`	`53`	`]`
`50`	`54`	`},`
`51`	`55`	`{`
`52`		`- text: '其他',`
	`56`	`+ text: "其他",`
`53`	`57`	`items: [`
`54`	`58`	`{`
`55`		`- text: '从 0.x 迁移',`
`56`		`- link: '/zh/miscellaneous/migration-guide.html'`
	`59`	`+ text: "从 0.x 迁移",`
	`60`	`+ link: "/zh/miscellaneous/migration-guide.html"`
`57`	`61`	`},`
`58`	`62`	`{`
`59`		`- text: 'Changelog',`
`60`		`- link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md'`
	`63`	`+ text: "Changelog",`
	`64`	`+ link: "https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md"`
`61`	`65`	`}`
`62`	`66`	`]`
`63`	`67`	`}`
`64`	`68`	`]`
`65`	`69`	`},`
`66`	`70`	`{`
`67`		`- text: '0.x',`
`68`		`- link: 'https://vuepress.vuejs.org/'`
`69`		`- },`
`70`		`-]`
	`71`	`+ text: "0.x",`
	`72`	`+ link: "https://vuepress.vuejs.org/"`
	`73`	`+ }`
	`74`	`+];`