From c7230b4120371e08bc1b99dfb61c665b03818015 Mon Sep 17 00:00:00 2001 From: xzchaoo Date: Tue, 7 Mar 2023 15:49:41 +0800 Subject: [PATCH] docs: Refer to 'ceresdb/doc' for better language switch --- .github/workflows/deploy-docs.yml | 16 +- docs/README.md | 34 +- docs/README_CN.md | 35 +- docs/agg/index.html | 23 - docs/book.toml | 29 ++ docs/en/book.toml | 8 - docs/move.sh | 8 + docs/sidebar.js | 66 +++ docs/{zh/src => src/cn}/SUMMARY.md | 0 .../cn}/dev-guide/build/build-docker-image.md | 0 .../src => src/cn}/dev-guide/build/compile.md | 0 .../cn/introduction/what-is-holoinsight.md | 11 + .../src => src/cn}/user-guide/introduction.md | 0 docs/{en/src => src/en}/SUMMARY.md | 0 .../en}/dev-guide/build/build-docker-image.md | 0 .../src => src/en}/dev-guide/build/compile.md | 0 .../dev-guide/build/docker-image-details.md | 0 .../en}/dev-guide/ddl-management.md | 0 .../en}/dev-guide/dev-requirements.md | 0 .../src => src/en}/dev-guide/log/README.md | 0 .../en}/dev-guide/project-structure.md | 0 .../src => src/en}/dev-guide/run/README.md | 0 .../dev-guide/run/bootstrap-configuration.md | 0 .../dev-guide/run/dynamic-configuration.md | 0 .../src => src/en}/dev-guide/test/README.md | 0 .../en}/introduction/quick-start.md | 0 .../en}/introduction/what-is-holoinsight.md | 5 + .../src => src/en}/user-guide/introduction.md | 0 docs/style.css | 48 ++ docs/theme/index.hbs | 418 ++++++++++++++++++ docs/zh/book.toml | 8 - .../src/introduction/what-is-holoinsight.md | 2 - scripts/build.sh | 6 + scripts/install.sh | 5 + scripts/serve.sh | 6 + 35 files changed, 647 insertions(+), 81 deletions(-) delete mode 100644 docs/agg/index.html create mode 100644 docs/book.toml delete mode 100644 docs/en/book.toml create mode 100644 docs/move.sh create mode 100644 docs/sidebar.js rename docs/{zh/src => src/cn}/SUMMARY.md (100%) rename docs/{zh/src => src/cn}/dev-guide/build/build-docker-image.md (100%) rename docs/{zh/src => src/cn}/dev-guide/build/compile.md (100%) create mode 100644 docs/src/cn/introduction/what-is-holoinsight.md rename docs/{zh/src => src/cn}/user-guide/introduction.md (100%) rename docs/{en/src => src/en}/SUMMARY.md (100%) rename docs/{en/src => src/en}/dev-guide/build/build-docker-image.md (100%) rename docs/{en/src => src/en}/dev-guide/build/compile.md (100%) rename docs/{en/src => src/en}/dev-guide/build/docker-image-details.md (100%) rename docs/{en/src => src/en}/dev-guide/ddl-management.md (100%) rename docs/{en/src => src/en}/dev-guide/dev-requirements.md (100%) rename docs/{en/src => src/en}/dev-guide/log/README.md (100%) rename docs/{en/src => src/en}/dev-guide/project-structure.md (100%) rename docs/{en/src => src/en}/dev-guide/run/README.md (100%) rename docs/{en/src => src/en}/dev-guide/run/bootstrap-configuration.md (100%) rename docs/{en/src => src/en}/dev-guide/run/dynamic-configuration.md (100%) rename docs/{en/src => src/en}/dev-guide/test/README.md (100%) rename docs/{en/src => src/en}/introduction/quick-start.md (100%) rename docs/{en/src => src/en}/introduction/what-is-holoinsight.md (64%) rename docs/{en/src => src/en}/user-guide/introduction.md (100%) create mode 100644 docs/style.css create mode 100644 docs/theme/index.hbs delete mode 100644 docs/zh/book.toml delete mode 100644 docs/zh/src/introduction/what-is-holoinsight.md create mode 100755 scripts/build.sh create mode 100755 scripts/install.sh create mode 100755 scripts/serve.sh diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 708edd2..0c001c1 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -11,7 +11,7 @@ on: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: - contents: write + contents: read pages: write id-token: write @@ -32,14 +32,20 @@ jobs: uses: peaceiris/actions-mdbook@v1 with: mdbook-version: 'latest' + - name: Cache Rust Dependencies + uses: actions/cache@v3 + with: + path: | + ~/.cargo + key: docs-${{ runner.os }} + - name: Install mdBook & mdBook-i18n + run: ./scripts/install.sh - name: Build docs - run: mdbook build ./docs/en && mdbook build ./docs/zh - - name: Build agg - run: mv ./docs/en/book ./docs/agg/en && mv ./docs/zh/book ./docs/agg/zh + run: sed -i 's|var basePath = "/";|var basePath = "/holoinsight-docs/";|' ./docs/theme/index.hbs && ./scripts/build.sh - name: Upload docs uses: actions/upload-pages-artifact@v1 with: - path: ./docs/agg + path: ./docs/book/html deploy-docs: environment: name: github-pages diff --git a/docs/README.md b/docs/README.md index 17d28ee..da98e54 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,35 +1,35 @@ # README -# Install mdBook +# Install mdBook & mdBook-i18n -Download mdBook from its [release page](https://github.com/rust-lang/mdBook/releases) and put it on your `$PATH`. +You should install `Rust lang` first. -Verify mdBook: -```bash -mdbook --version -``` +Check [this doc](https://www.rust-lang.org/learn/get-started). -output: -```text -mdbook v0.4.26 +Then install mdBook & mdBook-i18n using `cargo`: + +```bash +./scripts/install.sh ``` -Read [mdBook Documentation](https://rust-lang.github.io/mdBook/format/summary.html) +Read [mdBook Documentation](https://rust-lang.github.io/mdBook/format/summary.html) for more details. # Write documentations Directory structure: ```text docs/ - en/ English translation - src/ + book/ -> Build book result, ignored by git + src/ + en/ -> English translation introduction/ - introduction.md A documentation - SUMMARY.md A markdown which generates the sidebar menu. Check the detail here https://rust-lang.github.io/mdBook/format/summary.html - zh/ Chinese translation, has same directory structure as en/ + introduction.md -> A markdown + SUMMARY.md -> A markdown which generates the sidebar menu. Check the detail here https://rust-lang.github.io/mdBook/format/summary.html + cn/ -> Chinese translation. It has same directory structure as 'en/'. + resources/ -> Static resources ``` -The 'mdbook serve' command is used to preview a book by serving it via HTTP at `localhost:3000` by default: +The './scripts/serve.sh' command is used to preview a book by serving it via HTTP at `localhost:3000` by default: ```bash -mdbook serve ./docs/en +./scripts/serve.sh ``` diff --git a/docs/README_CN.md b/docs/README_CN.md index 6c23d49..bbdade1 100644 --- a/docs/README_CN.md +++ b/docs/README_CN.md @@ -1,35 +1,34 @@ # README -# 安装 mdBook +# 安装 mdBook 和 mdBook-i18n -从 [release page](https://github.com/rust-lang/mdBook/releases) 下载 mdBook，并将其放置在 `$PATH` 下. +你需要先安装 Rust 语言. -验证 mdBook: -```bash -mdbook --version -``` +请参考这个文档 [this doc](https://www.rust-lang.org/learn/get-started). -输出: -```text -mdbook v0.4.26 +使用 `cargo` 安装 mdBook 和 mdBook-i18n: + +```bash +./scripts/install.sh ``` -阅读 [mdBook 文档](https://rust-lang.github.io/mdBook/format/summary.html) +更多详情请阅读 [mdBook 文档](https://rust-lang.github.io/mdBook/format/summary.html) # 编写文档 目录结构： ```text docs/ - en/ 英文翻译 - src/ - introduction/ - introduction.md 一个文档 - SUMMARY.md 一个 markdown 文档，用于生成侧边菜单栏. 详情请参考 mdBook 文档。 - zh/ 中文翻译，与 en/ 有相同的目录结构。 + book/ -> 书的构建结果，会被 git 忽略 + src/ + en/ 英文翻译 + introduction/ + introduction.md -> 一个文档 + SUMMARY.md -> 一个 markdown 文档，用于生成侧边菜单栏. 详情请参考 mdBook 文档。 + cn/ -> 中文翻译，与 en/ 有相同的目录结构。 ``` -使用 'mdbook serve' 命令在 `localhost:3000` 部署一个 HTTP 服务器用于预览渲染结果。 +使用 './scripts/serve.sh' 命令在 `localhost:3000` 部署一个 HTTP 服务器用于预览渲染结果。 ```bash -mdbook serve ./docs/en +./scripts/serve.sh ``` diff --git a/docs/agg/index.html b/docs/agg/index.html deleted file mode 100644 index 190517f..0000000 --- a/docs/agg/index.html +++ /dev/null @@ -1,23 +0,0 @@ - - - - HoloInsight Documentations - - - - - - - -
- -
- - diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..157a87e --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,29 @@ +[book] +title = "HoloInsight Documentation" +authors = ["HoloInsight Authors"] +src = "src/en" +language = "en" +multilingual = true + +[build] +use-default-preprocessors = false + + +[preprocessor.links] + +[[output.i18n.translations]] +src = "src/cn" +language = "cn" +translators = ["HoloInsight Authors"] +title = "HoloInsight 文档" + +[output.random] +command = "/bin/bash ../../move.sh" + +[output.html] +site-url = "/holoinsight-docs/" +additional-css = ["style.css"] +additional-js = ["sidebar.js"] + +[output.html.fold] +enable = true diff --git a/docs/en/book.toml b/docs/en/book.toml deleted file mode 100644 index 0bda139..0000000 --- a/docs/en/book.toml +++ /dev/null @@ -1,8 +0,0 @@ -[book] -title = "HoloInsight Documentations" -authors = ["xzchaoo"] -language = "en" -src = "src" - -[build] -create-missing = false diff --git a/docs/move.sh b/docs/move.sh new file mode 100644 index 0000000..74dffb7 --- /dev/null +++ b/docs/move.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -e + +echo "ready to move files" +cp -r ../i18n/cn ../html/cn +cp -r ../i18n/en ../html/en +cp -r ../../src/resources ../../book/html/resources +echo "copy done" diff --git a/docs/sidebar.js b/docs/sidebar.js new file mode 100644 index 0000000..bd73342 --- /dev/null +++ b/docs/sidebar.js @@ -0,0 +1,66 @@ +// Un-active everything when you click it +Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el) { + el.addEventHandler("click", function() { + Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el) { + el.classList.remove("active"); + }); + el.classList.add("active"); + }); +}); + +var updateFunction = function() { + + var id; + var elements = document.getElementsByClassName("header"); + Array.prototype.forEach.call(elements, function(el) { + if (window.pageYOffset >= el.offsetTop) { + id = el; + } + }); + + Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el) { + el.classList.remove("active"); + }); + + Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el) { + if (id.href.localeCompare(el.href) == 0) { + el.classList.add("active"); + } + }); +}; + +// Populate sidebar on load +window.addEventListener('load', function() { + var pagetoc = document.getElementsByClassName("pagetoc")[0]; + var elements = document.getElementsByClassName("header"); + Array.prototype.forEach.call(elements, function(el) { + var link = document.createElement("a"); + + // Indent shows hierarchy + var indent = ""; + switch (el.parentElement.tagName) { + case "H2": + indent = "20px"; + break; + case "H3": + indent = "40px"; + break; + case "H4": + indent = "60px"; + break; + default: + break; + } + + link.appendChild(document.createTextNode(el.text)); + link.style.paddingLeft = indent; + link.href = el.href; + pagetoc.appendChild(link); + }); + updateFunction.call(); +}); + + + +// Handle active elements on scroll +window.addEventListener("scroll", updateFunction); diff --git a/docs/zh/src/SUMMARY.md b/docs/src/cn/SUMMARY.md similarity index 100% rename from docs/zh/src/SUMMARY.md rename to docs/src/cn/SUMMARY.md diff --git a/docs/zh/src/dev-guide/build/build-docker-image.md b/docs/src/cn/dev-guide/build/build-docker-image.md similarity index 100% rename from docs/zh/src/dev-guide/build/build-docker-image.md rename to docs/src/cn/dev-guide/build/build-docker-image.md diff --git a/docs/zh/src/dev-guide/build/compile.md b/docs/src/cn/dev-guide/build/compile.md similarity index 100% rename from docs/zh/src/dev-guide/build/compile.md rename to docs/src/cn/dev-guide/build/compile.md diff --git a/docs/src/cn/introduction/what-is-holoinsight.md b/docs/src/cn/introduction/what-is-holoinsight.md new file mode 100644 index 0000000..5facf43 --- /dev/null +++ b/docs/src/cn/introduction/what-is-holoinsight.md @@ -0,0 +1,11 @@ +![HoloInsight](https://github.com/traas-stack/holoinsight/raw/main/docs/logo/logo.png) + +![License](https://img.shields.io/badge/license-Apache--2.0-green.svg) +[![OpenIssue](https://img.shields.io/github/issues/traas-stack/holoinsight)](https://github.com/CeresDB/ceresdb/issues) + +# 什么是 HoloInsight + +HoloInsight 关联项目: +* HoloInsight +* HoloInsight Agent +* HoloInsight Docs diff --git a/docs/zh/src/user-guide/introduction.md b/docs/src/cn/user-guide/introduction.md similarity index 100% rename from docs/zh/src/user-guide/introduction.md rename to docs/src/cn/user-guide/introduction.md diff --git a/docs/en/src/SUMMARY.md b/docs/src/en/SUMMARY.md similarity index 100% rename from docs/en/src/SUMMARY.md rename to docs/src/en/SUMMARY.md diff --git a/docs/en/src/dev-guide/build/build-docker-image.md b/docs/src/en/dev-guide/build/build-docker-image.md similarity index 100% rename from docs/en/src/dev-guide/build/build-docker-image.md rename to docs/src/en/dev-guide/build/build-docker-image.md diff --git a/docs/en/src/dev-guide/build/compile.md b/docs/src/en/dev-guide/build/compile.md similarity index 100% rename from docs/en/src/dev-guide/build/compile.md rename to docs/src/en/dev-guide/build/compile.md diff --git a/docs/en/src/dev-guide/build/docker-image-details.md b/docs/src/en/dev-guide/build/docker-image-details.md similarity index 100% rename from docs/en/src/dev-guide/build/docker-image-details.md rename to docs/src/en/dev-guide/build/docker-image-details.md diff --git a/docs/en/src/dev-guide/ddl-management.md b/docs/src/en/dev-guide/ddl-management.md similarity index 100% rename from docs/en/src/dev-guide/ddl-management.md rename to docs/src/en/dev-guide/ddl-management.md diff --git a/docs/en/src/dev-guide/dev-requirements.md b/docs/src/en/dev-guide/dev-requirements.md similarity index 100% rename from docs/en/src/dev-guide/dev-requirements.md rename to docs/src/en/dev-guide/dev-requirements.md diff --git a/docs/en/src/dev-guide/log/README.md b/docs/src/en/dev-guide/log/README.md similarity index 100% rename from docs/en/src/dev-guide/log/README.md rename to docs/src/en/dev-guide/log/README.md diff --git a/docs/en/src/dev-guide/project-structure.md b/docs/src/en/dev-guide/project-structure.md similarity index 100% rename from docs/en/src/dev-guide/project-structure.md rename to docs/src/en/dev-guide/project-structure.md diff --git a/docs/en/src/dev-guide/run/README.md b/docs/src/en/dev-guide/run/README.md similarity index 100% rename from docs/en/src/dev-guide/run/README.md rename to docs/src/en/dev-guide/run/README.md diff --git a/docs/en/src/dev-guide/run/bootstrap-configuration.md b/docs/src/en/dev-guide/run/bootstrap-configuration.md similarity index 100% rename from docs/en/src/dev-guide/run/bootstrap-configuration.md rename to docs/src/en/dev-guide/run/bootstrap-configuration.md diff --git a/docs/en/src/dev-guide/run/dynamic-configuration.md b/docs/src/en/dev-guide/run/dynamic-configuration.md similarity index 100% rename from docs/en/src/dev-guide/run/dynamic-configuration.md rename to docs/src/en/dev-guide/run/dynamic-configuration.md diff --git a/docs/en/src/dev-guide/test/README.md b/docs/src/en/dev-guide/test/README.md similarity index 100% rename from docs/en/src/dev-guide/test/README.md rename to docs/src/en/dev-guide/test/README.md diff --git a/docs/en/src/introduction/quick-start.md b/docs/src/en/introduction/quick-start.md similarity index 100% rename from docs/en/src/introduction/quick-start.md rename to docs/src/en/introduction/quick-start.md diff --git a/docs/en/src/introduction/what-is-holoinsight.md b/docs/src/en/introduction/what-is-holoinsight.md similarity index 64% rename from docs/en/src/introduction/what-is-holoinsight.md rename to docs/src/en/introduction/what-is-holoinsight.md index 9714f09..88a6b98 100644 --- a/docs/en/src/introduction/what-is-holoinsight.md +++ b/docs/src/en/introduction/what-is-holoinsight.md @@ -1,3 +1,8 @@ +![HoloInsight](https://github.com/traas-stack/holoinsight/raw/main/docs/logo/logo.png) + +![License](https://img.shields.io/badge/license-Apache--2.0-green.svg) +[![OpenIssue](https://img.shields.io/github/issues/traas-stack/holoinsight)](https://github.com/CeresDB/ceresdb/issues) + # What is HoloInsight HoloInsight is a cloud-native observability platform with a special focus on real-time log analysis and AI integration. You can check the following documentation for more information. diff --git a/docs/en/src/user-guide/introduction.md b/docs/src/en/user-guide/introduction.md similarity index 100% rename from docs/en/src/user-guide/introduction.md rename to docs/src/en/user-guide/introduction.md diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..5cb20e5 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,48 @@ +@media only screen and (max-width:1439px) { + .sidetoc { + display: none; + } +} + +@media only screen and (min-width:1440px) { + main { + position: relative; + } + .sidetoc { + margin-left: auto; + margin-right: auto; + left: calc(100% + (var(--content-max-width))/4 - 140px); + position: absolute; + } + .pagetoc { + position: fixed; + width: 200px; + height: calc(100vh - var(--menu-bar-height) - 0.67em * 4); + overflow: auto; + } + .pagetoc a { + border-left: 1px solid var(--sidebar-bg); + color: var(--fg) !important; + display: block; + padding-bottom: 5px; + padding-top: 5px; + padding-left: 10px; + text-align: left; + text-decoration: none; + } + .pagetoc a:hover, + .pagetoc a.active { + background: var(--sidebar-bg); + color: var(--sidebar-fg) !important; + } + .pagetoc .active { + background: var(--sidebar-bg); + color: var(--sidebar-fg); + } +} + +@media print { + .sidetoc { + display: none; + } +} diff --git a/docs/theme/index.hbs b/docs/theme/index.hbs new file mode 100644 index 0000000..7ab4235 --- /dev/null +++ b/docs/theme/index.hbs @@ -0,0 +1,418 @@ + + + + + + {{ title }} + {{#if is_print }} + + {{/if}} + {{#if base_url}} + + {{/if}} + + + + {{> head}} + + + + + + + {{#if favicon_svg}} + + {{/if}} + {{#if favicon_png}} + + {{/if}} + + + + {{#if print_enable}} + + {{/if}} + + + + {{#if copy_fonts}} + + {{/if}} + + + + + + + + {{#each additional_css}} + + {{/each}} + + {{#if mathjax_support}} + + + {{/if}} + + + + + + + + + + + + + + + + +
+ +
+ {{> header}} + + + + + + {{#if search_enabled}} + + {{/if}} + + + + +
+
+ +
+ + {{{ content }}} +
+ + +
+
+ + + +
+ + {{#if live_reload_endpoint}} + + + {{/if}} + + {{#if google_analytics}} + + + {{/if}} + + {{#if playground_line_numbers}} + + {{/if}} + + {{#if playground_copyable}} + + {{/if}} + + {{#if playground_js}} + + + + + + {{/if}} + + {{#if search_js}} + + + + {{/if}} + + + + + + + {{#each additional_js}} + + {{/each}} + + {{#if is_print}} + {{#if mathjax_support}} + + {{else}} + + {{/if}} + {{/if}} + + + + + + diff --git a/docs/zh/book.toml b/docs/zh/book.toml deleted file mode 100644 index 2d80efd..0000000 --- a/docs/zh/book.toml +++ /dev/null @@ -1,8 +0,0 @@ -[book] -title = "HoloInsight 文档" -authors = ["xzchaoo"] -language = "zh" -src = "src" - -[build] -create-missing = false diff --git a/docs/zh/src/introduction/what-is-holoinsight.md b/docs/zh/src/introduction/what-is-holoinsight.md deleted file mode 100644 index 4a7481f..0000000 --- a/docs/zh/src/introduction/what-is-holoinsight.md +++ /dev/null @@ -1,2 +0,0 @@ -# 什么是 HoloInsight -TODO diff --git a/scripts/build.sh b/scripts/build.sh new file mode 100755 index 0000000..7f94529 --- /dev/null +++ b/scripts/build.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -e + +cd `dirname $0`/.. + +mdbook build ./docs diff --git a/scripts/install.sh b/scripts/install.sh new file mode 100755 index 0000000..40b4c95 --- /dev/null +++ b/scripts/install.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +set -e + +cargo install mdbook@0.4.25 +cargo install mdbook-i18n --git https://github.com/chunshao90/mdbook-i18n.git --rev ca497cff369e0a5cedcd4024af6e1f05cc5050c5 diff --git a/scripts/serve.sh b/scripts/serve.sh new file mode 100755 index 0000000..7075930 --- /dev/null +++ b/scripts/serve.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -e + +cd `dirname $0`/.. + +mdbook serve ./docs