c02625efa9
I started a discussion on this before, you can check it in the mail group https://lists.apache.org/thread/o770bc3k623kyfks2mzkt21qsc4g6328 In order to facilitate everyone to organize the documents, I created a new-docs directory under the incubator-doris directory. The new directory structure is below this. I just created a directory structure here, which needs to be rearranged. In the data import scenario, in order to take into account the viewing habits of previous users, the import is organized in two ways: 1. According to the usage scenario: This will give users clearer guidance. For example, the user is the data source of kafka, then the user can directly select the routine to load 2. According to the import method: it is the introduction of the various import methods we provided before In order to facilitate everyone to run and debug locally, I migrated the entire .vuepress under the original document. After completion, you only need to delete the original docs directory and rename the new new-docs directory to docs. At the same time, you can also run it locally, so that you can organize documents and know the content of each document directory. In the local debugging execution, switch to the new-docs directory and execute the following command: ```` npm install npm run dev ```` then through the browser http://ip:port/zh-CN http://ip:port/en
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: -
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.mdThen 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 lintbefore 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.
FullText search
We use Algolia DocSearch as our fulltext search engine.
One thing we need to do is that Config.json From DocSearch should be updated if a new language or branch is created.
For more detail of the docsearch's configuration, please refer to Configuration of DocSearch
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 thebaseproperty). -
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"
}
]
}
]
}