You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@doris.apache.org by GitBox <gi...@apache.org> on 2020/04/28 03:49:20 UTC
[GitHub] [incubator-doris] hffariel opened a new issue #3408: [Enhancement]Document rebuild with Vuepress.
hffariel opened a new issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408
## Motivation
As we see, our documents' website now has some disadvantages like: old fashioned design, mobile incompatible, lack of version control, etc. So i'm trying to rebuild our website with Vuepress which is a minimalistic Vue-powered static site generator.
## A whole new look
By doing this, we'll have some new features like: more friendly UI, better localization, new version management. And it'll be like:
## Implementation
1. Docs' directory will be with a new structure:
```bash
.
├─ docs/
│ ├─ .vuepress
│ │ ├─ dist // Built site files.
│ │ ├─ public // Assets
│ │ ├─ sidebar // Side bar configurations.
│ │ │ ├─ en.js
│ │ │ └─ zh-CN.js
│ ├─ theme // Global styles and customizations.
│ └─ config.js // Vuepress configurations.
├─ zh-CN/
│ ├─ xxxx.md
│ └─ README.md // Will be rendered as entry page.
└─ en/
├─ xxxx.md
└─ README.md // Will be rendered as entry page.
```
2. New way of writing a document may be changed a little bit.
* Write in multi languages and put them in separated folders `./en/` and `./zh-CN/`. **But they should be with the same name.**
```bash
.
├─ en/
│ ├─ one.md
│ └─ two.md
└─ zh-CN/
│ ├─ one.md
│ └─ two.md
```
* Frontmatters like below should always be on the top of each file:
```markdown
---
{
"title": "Backup and Recovery", // sidebar title
"language": "en" // writing language
}
---
```
* Assets are in `.vuepress/public/`.
Assuming that there exists a png `.vuepress/public/images/image_x.png`, then it can be used like:
```markdown
```
* Sidebar configurations in `.vuepress/sidebar/` need to be updated after adding a new file or a folder.
Assuming that the directories are:
```bash
.
├─ en/
│ ├─ subfolder
│ │ ├─ one.md
│ │ └─ two.md
│ └─ three.md
└─ zh-CN/
├─ subfolder
│ ├─ one.md
│ └─ two.md
└─ three.md
```
Then the sidebar configurations would be like:
```nodejs
// .vuepress/sidebar/en.js`
module.exports = [
{
title: "subfolder name",
directoryPath: "subfolder/",
children: ["one", "two"]
},
"three"
]
```
```nodejs
// .vuepress/sidebar/zh-CN.js
module.exports = [
{
title: "文件夹名称",
directoryPath: "subfolder/",
children: ["one", "two"]
},
"three"
]
```
3. TravisCI will be integrated for auto building.
Once a PR accepted, TravisCI will be triggered to build all the document files within its own branch. Then push them to a separated directory in https://github.com/apache/incubator-doris-website.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] hffariel edited a comment on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
hffariel edited a comment on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620393344
@morningman
> Do you mean a new branch in https://github.com/apache/incubator-doris-website?
No, separated directories are all in branch `afs-site`, for multi-version management.
And the asf-site branch will be like:
```bash
.
├─ master/
│ ├─ en/
│ │ ├─ subfolder
│ │ │ ├─ one.md
│ │ └─ three.md
│ └─ zh-CN/
│ ├─ subfolder
│ │ ├─ one.md
│ └─ three.md
├─ branch-0.11/
│ ├─ en/
│ │ ├─ subfolder
│ │ │ ├─ one.md
│ │ └─ three.md
│ └─ zh-CN/
│ ├─ subfolder
│ │ ├─ one.md
│ └─ three.md
├─ index.html // user entry, and auto redirected to master folder
└─ versions.json // all versions that can be seleted on the website are defined here
```
And the `versions.json` is for `version options` configuring:
```json
{
"en": [
{
"text": "Versions", // dropdown label
"items": [
{
"text": "master", // dropdown-item label
"link": "/../master/en/installing/compilation.html", // entry page for this version
"target": "_blank"
},
{
"text": "incubating-test",
"link": "/../branch-0.11/en/installing/compilation.html",
"target": "_blank"
}
]
}
],
"zh-CN": [
{
"text": "版本",
"items": [
{
"text": "master",
"link": "/../master/zh-CN/installing/compilation.html",
"target": "_blank"
},
{
"text": "incubating-test",
"link": "/../incubating-test/zh-CN/installing/compilation.html",
"target": "_blank"
}
]
}
]
}
```
> Have you done most of the migration?
Yeah, i've done most part of the migration, but there still exists some markdown lint problems which are not that important at this stage. And of course these lint problems would be fixed in the next few days.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] hffariel commented on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
hffariel commented on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620393344
> Do you mean a new branch in https://github.com/apache/incubator-doris-website?
1. No, separated directories are all in branch `afs-site`, for multi-version management.
And the asf-site branch will be like:
```bash
.
├─ master/
│ ├─ en/
│ │ ├─ subfolder
│ │ │ ├─ one.md
│ │ └─ three.md
│ └─ zh-CN/
│ ├─ subfolder
│ │ ├─ one.md
│ └─ three.md
├─ branch-0.11/
│ ├─ en/
│ │ ├─ subfolder
│ │ │ ├─ one.md
│ │ └─ three.md
│ └─ zh-CN/
│ ├─ subfolder
│ │ ├─ one.md
│ └─ three.md
├─ index.html // user entry, and auto redirected to master folder
└─ versions.json // all versions that can be seleted on the website are defined here
```
And the `versions.json` is for `version options` configuring:
```json
{
"en": [
{
"text": "Versions", // dropdown label
"items": [
{
"text": "master", // dropdown-item label
"link": "/../master/en/installing/compilation.html", // entry page for this version
"target": "_blank"
},
{
"text": "incubating-test",
"link": "/../branch-0.11/en/installing/compilation.html",
"target": "_blank"
}
]
}
],
"zh-CN": [
{
"text": "版本",
"items": [
{
"text": "master",
"link": "/../master/zh-CN/installing/compilation.html",
"target": "_blank"
},
{
"text": "incubating-test",
"link": "/../incubating-test/zh-CN/installing/compilation.html",
"target": "_blank"
}
]
}
]
}
```
> Have you done most of the migration?
Yeah, i've done most part of the migration, but there still exists some markdown lint problems which are not that important at this stage. And of course these lint problems would be fixed in the next few days.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] hffariel commented on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
hffariel commented on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620405276
@morningman
Could be done by adding these lines to travis.yml ? Sure, it may looks like a trick though.
```yaml
- export PR=https://api.github.com/repos/$TRAVIS_REPO_SLUG/pulls/$TRAVIS_PULL_REQUEST
- export BRANCH=$(if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then echo $TRAVIS_BRANCH; else echo `curl -s $PR | jq -r .head.ref`; fi)
- echo $BRANCH
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] morningman commented on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
morningman commented on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620403347
> No, separated directories are all in branch `afs-site`, for multi-version management.
But how do you know which directory should be pushed to for a certain PR? Or do you mean to
push all new PRs to the directory of latest version?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] hffariel edited a comment on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
hffariel edited a comment on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620405276
@morningman
Could be done by adding these lines to travis.yml ? Sure, it may looks like a trick though.
```yaml
- export PR=https://api.github.com/repos/$TRAVIS_REPO_SLUG/pulls/$TRAVIS_PULL_REQUEST
- export BRANCH=$(if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then echo $TRAVIS_BRANCH; else echo `curl -s $PR | jq -r .head.ref`; fi)
- echo $BRANCH
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] hffariel commented on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
hffariel commented on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620440670
@morningman No problem, feel free to talk further.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] morningman commented on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
morningman commented on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620427360
> Could be done by adding these lines to travis.yml ? Sure, it may looks like a trick though.
OK I see. Thank you~
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] morningman commented on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
morningman commented on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620374777
Nice Job.
I have a question about building: You said `Then push them to a separated directory`, what is `a separated directory`? Do you mean a new branch in `https://github.com/apache/incubator-doris-website`? Can it be auto pushed to the branch `afs-site`?
And how to migrate the current docs? Have you done most of the migration, or do you need us to complete the migration together?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org
[GitHub] [incubator-doris] hffariel edited a comment on issue #3408: [Enhancement]Document rebuild with Vuepress.
Posted by GitBox <gi...@apache.org>.
hffariel edited a comment on issue #3408:
URL: https://github.com/apache/incubator-doris/issues/3408#issuecomment-620393344
@morningman
> Do you mean a new branch in https://github.com/apache/incubator-doris-website?
1. No, separated directories are all in branch `afs-site`, for multi-version management.
And the asf-site branch will be like:
```bash
.
├─ master/
│ ├─ en/
│ │ ├─ subfolder
│ │ │ ├─ one.md
│ │ └─ three.md
│ └─ zh-CN/
│ ├─ subfolder
│ │ ├─ one.md
│ └─ three.md
├─ branch-0.11/
│ ├─ en/
│ │ ├─ subfolder
│ │ │ ├─ one.md
│ │ └─ three.md
│ └─ zh-CN/
│ ├─ subfolder
│ │ ├─ one.md
│ └─ three.md
├─ index.html // user entry, and auto redirected to master folder
└─ versions.json // all versions that can be seleted on the website are defined here
```
And the `versions.json` is for `version options` configuring:
```json
{
"en": [
{
"text": "Versions", // dropdown label
"items": [
{
"text": "master", // dropdown-item label
"link": "/../master/en/installing/compilation.html", // entry page for this version
"target": "_blank"
},
{
"text": "incubating-test",
"link": "/../branch-0.11/en/installing/compilation.html",
"target": "_blank"
}
]
}
],
"zh-CN": [
{
"text": "版本",
"items": [
{
"text": "master",
"link": "/../master/zh-CN/installing/compilation.html",
"target": "_blank"
},
{
"text": "incubating-test",
"link": "/../incubating-test/zh-CN/installing/compilation.html",
"target": "_blank"
}
]
}
]
}
```
> Have you done most of the migration?
Yeah, i've done most part of the migration, but there still exists some markdown lint problems which are not that important at this stage. And of course these lint problems would be fixed in the next few days.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org