Doris Document

Vuepress is used as our document site generator, configurations are in ./docs/.vuepress folder.

Getting Started

Download and install nodejs

npm config set registry https://registry.npm.taobao.org // Only if you are in Mainland China.
cd docs && npm install
npm run dev

Open your browser and navigate to localhost:8080/en/ or localhost:8080/zh-CN/.

Docs' Directories

  .
  ├─ 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/
     ├─ one.md
     └─ README.md // Will be rendered as entry page.

Start Writing

Write markdown files 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)
```

Remember to update the sidebar configurations in .vuepress/sidebar/ 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"
]

Run npm run lint before starting a PR.

Surely that there will be lots of error logs if the mardown files are not following the rules, and these logs will all be printed in the console:

en/administrator-guide/alter-table/alter-table-bitmap-index.md:92 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "    ```"]
en/administrator-guide/alter-table/alter-table-rollup.md:45 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-rollup.md:77 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-rollup.md:178 MD046/code-block-style Code block style [Expected: fenced; Actual: indented]
en/administrator-guide/alter-table/alter-table-schema-change.md:50 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-schema-change.md:82 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-schema-change.md:127 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-schema-change.md:144 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-schema-change.md:153 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
en/administrator-guide/alter-table/alter-table-schema-change.md:199 MD046/code-block-style Code block style [Expected: fenced; Actual: indented]
en/administrator-guide/backup-restore.md:45:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]
en/administrator-guide/backup-restore.md:57:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]
en/administrator-guide/backup-restore.md:61:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 3; Style: 1/1/1]
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! docs@ lint: `markdownlint '**/*.md' -f`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the docs@ lint script.

Deployment

Just start a PR, and all things will be done automatically.

What Travis Does

Once a PR accepted, travis ci will be triggered to build and deploy the whole website within its own branch. Here is what .travis.yml does:

Prepare nodejs and vuepress enviorment.
Use current branch's name as the relative url path in .vuepress/config.js(which is the base property).
Build the documents into a website all by vuepress.
Fetch asf-site repo to local directory, and copy .vupress/dist/ into {BRANCH}/.
Push the new site to asf-site repo with GitHub Token(which is preset in Travis console as a variable used in .travis.yml).

asf-site repository

Finally the asf-site repository will be like:

.
├─ master/
│  ├─ en/
│  │  ├─ subfolder
│  │  │  ├─ one.md
│  │  └─ three.md
│  └─ zh-CN/
│      ├─ subfolder
│      │  ├─ one.md
│      └─ three.md
├─ incubating-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 like:

{
  "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": "branch-0.11",
          "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": "branch-0.11",
          "link": "/../branch-0.11/zh-CN/installing/compilation.html",
          "target": "_blank"
        }
      ]
    }
  ]
}

hffariel / test-docs