[Enhancement]Document rebuild with Vuepress.

[hffariel]

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:

  .
  ├─ 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.

   • Write in multi languages and put them in separated folders ./en/ and ./zh-CN/. But they should be with the same name.

   .
   ├─ en/
   │  ├─ one.md
   │  └─ two.md
   └─ zh-CN/
   │  ├─ one.md
   │  └─ two.md

   • Frontmatters like below should always be on the top of each file:

   ---
   {
       "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:

   ![alter text](/images/image_x.png)

   • Sidebar configurations in .vuepress/sidebar/ need to be updated after adding a new file or a folder.

   Assuming that the directories are:

   .
   ├─ en/
   │  ├─ subfolder
   │  │  ├─ one.md
   │  │  └─ two.md
   │  └─ three.md
   └─ zh-CN/
      ├─ subfolder
      │  ├─ one.md
      │  └─ two.md
      └─ three.md

   Then the sidebar configurations would be like:

   // .vuepress/sidebar/en.js`
   module.exports = [
     {
       title: "subfolder name",
       directoryPath: "subfolder/",
       children: ["one", "two"]
     },
     "three"
   ]
   

   // .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.

[morningman]

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?

[hffariel]

@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:

.
├─ 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:

{
  "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.

[morningman]

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?

[hffariel]

@morningman

Could be done by adding these lines to travis.yml ? Sure, it may looks like a trick though.

 - 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

[morningman]

Could be done by adding these lines to travis.yml ? Sure, it may looks like a trick though.

OK I see. Thank you~

[hffariel]

@morningman No problem, feel free to talk further.