You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kylin.apache.org by xx...@apache.org on 2022/12/23 06:19:01 UTC
[kylin] 01/03: add mac troubleshooting content of how_to_write_doc
This is an automated email from the ASF dual-hosted git repository.
xxyu pushed a commit to branch doc5.0
in repository https://gitbox.apache.org/repos/asf/kylin.git
commit 5c25707fe9d2f846726ebf63821e0a6b594696f6
Author: pengfei.zhan <de...@gmail.com>
AuthorDate: Sun Dec 18 19:39:35 2022 +0800
add mac troubleshooting content of how_to_write_doc
---
website/docs/development/how_to_write_doc.md | 88 +++++++++++++++-------------
1 file changed, 47 insertions(+), 41 deletions(-)
diff --git a/website/docs/development/how_to_write_doc.md b/website/docs/development/how_to_write_doc.md
index 3d12743dc0..87cfbf7a8c 100644
--- a/website/docs/development/how_to_write_doc.md
+++ b/website/docs/development/how_to_write_doc.md
@@ -1,8 +1,8 @@
---
-title: How to write document
+title: How to write a document
language: en
-sidebar_label: How to write document
-pagination_label: How to write document
+sidebar_label: How to write a document
+pagination_label: How to write a document
toc_min_heading_level: 2
toc_max_heading_level: 6
pagination_prev: development/how_to_contribute
@@ -16,19 +16,19 @@ last_update:
author: Tengting Xu, Xiaoxiang Yu
---
-From Kylin 5.0, Kylin documents are written using [Docusaurus](https://docusaurus.io/). Please note multi-version and i18n (multi-language) is not supported right now, but is in the plan. Contributions are very much appreciated.
+From Kylin 5.0, Kylin documents are written using [Docusaurus](https://docusaurus.io/). Please note that multi-version and i18n (multi-language) are not supported right now but are in the plan. Contributions are very much appreciated.
### Shortcut: Edit a single existing page
:::info Shortcut editing a single page
-1. This shortcut is extreme useful if you found some minor typos or mistakes on a single page, you can edit the document in browser right away in a few minutes without preparation.
-2. But if the change is more complex, like add/edit several pages, upload images, or change global config files, please jump to next paragraph: [**Before your work**](#Before_your_work).
+1. This shortcut is extremely useful if you found some minor typos or mistakes on a single page, you can edit the document in the browser right away in a few minutes without preparation.
+2. But if the change is more complex, like adding/editing several pages, uploading images, or changing global config files, please jump to the next paragraph: [**Before your work**](#Before_your_work).
:::
1. Just scroll down the page to the bottom and click the `Edit this page`.
-2. Edit this file in browser.
+2. Edit this file in the browser.
3. Propose your changes by raising a pull request.
@@ -38,21 +38,21 @@ From Kylin 5.0, Kylin documents are written using [Docusaurus](https://docusauru
### <span id="Before_your_work">Before your work</span>
-Before adding new documentation, it is best to setup the preview environment first.
+Before adding new documentation, it is best to set up the preview environment first.
1. Install Node.js
- Make sure [Node.js](https://nodejs.org/en/download/) version is 16.14 or above by checking `node -v`. You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed.
+ Make sure the [Node.js](https://nodejs.org/en/download/) version is 16.14 or above by checking `node -v`. You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed.
```shell
node -v
```
:::note Tips
- When installing Node.js via *Windows/macOS Installer*, recommend to check all checkboxes related to dependencies.
+ When installing Node.js via *Windows/macOS Installer*, recommend checking all checkboxes related to dependencies.
:::
-2. Clone the kylin doc branch
+2. Clone the Kylin doc branch
```shell
cd /path/you/prefer/
@@ -68,7 +68,8 @@ Before adding new documentation, it is best to setup the preview environment fir
```
:::note Slow NPM in China?
- Add following lines to `~/.npmrc` and npm shall become much faster in China.
+ Add the following lines to `~/.npmrc` and npm shall become much faster in China.
+
```
sass_binary_site=https://npm.taobao.org/mirrors/node-sass/
phantomjs_cdnurl=https://npm.taobao.org/mirrors/phantomjs/
@@ -78,13 +79,18 @@ Before adding new documentation, it is best to setup the preview environment fir
:::
:::note Troubleshooting
- Depending on your OS environment, `npm install` can hit various issues at this stage and most of them are due to missing a certain library. Below are a few examples from a Ubuntu user.
- - If hit error `../src/common.cc:24:10: fatal error: vips/vips8: No such file or directory`
- - Try install glib2.0-dev, like `sudo apt-get install glib2.0-dev`
- - If hit error `Error: Command failed: /bin/sh -c autoreconf -ivf`
- - Try install autoconf, like `sudo apt-get install autoconf`
+ Depending on your OS environment, `npm install` may hit various issues at this stage, most of which are due to missing a certain library. Below are a few examples.
+
+ If an error is like the one below, for an Ubuntu user, it can be solved by installing the lib `glib2.0-dev` with **sudo apt-get install glib2.0-dev**.
+
+ > ../src/common.cc:24:10: fatal error: vips/vips8: No such file or directory
+
+ If an error is like the one below, for an Ubuntu user, it can be solved by installing the lib `autoconf` with **sudo apt-get install autoconf**, while for a macOS user, please try with **brew install autoconf automake libtool**.
+
+ > Error: Command failed: /bin/sh -c autoreconf -ivf
+
:::
-
+
For more information about [Docusaurus](https://docusaurus.io/), please refer to [Docusaurus Installation](https://docusaurus.io/docs/installation).
4. Launch the doc website and preview it locally
@@ -93,13 +99,13 @@ Before adding new documentation, it is best to setup the preview environment fir
npm run start
```
- The homepage of this doc site `http://localhost:3000` shall automatically open in your default browser if no error occurs. Modify any MD or resource file in your local repository, the changes shall reflect immediately in the browser. Very convenient for doc development.
+ The homepage of this doc site `http://localhost:3000` shall automatically open in your default browser if no error occurs. Modify any MD or resource file in your local repository, and the changes shall reflect immediately in the browser. Very convenient for doc development.
-### How to create new document
+### How to create a new document
#### Step 1: Create a new markdown file with metadata
-Create a new markdown file with any text editor, copy and paste following **Head Metadata Template** to the top your file. After that, replace the variables like `${TITLE OF NEW DOC}` with actual values.
+Create a new markdown file with any text editor, and copy and paste the following **Head Metadata Template** to the top of your file. After that, replace the variables like `${TITLE OF NEW DOC}` with actual values.
```
---
@@ -130,9 +136,9 @@ Add text in the [markdown format](https://docusaurus.io/docs/markdown-features).
Pictures usually go into a subfolder called `images`.
-#### Step 3: Add new page to the sidebar
+#### Step 3: Add a new page to the sidebar
-Sidebar contains the menu and the navigation tree of the doc site structure. It is maintained in a JS file located at `website/sidebars.js`.
+The sidebar contains the menu and the navigation tree of the doc site structure. It is maintained in a JS file located at `website/sidebars.js`.
For example, if you want to add a new doc `how_to_write_doc.md` to be the child of the `development` menu. Open the `sidebars.js` and modify the `DevelopmentSideBar` block. Add a new block at the tail of `items` of `DevelopmentSideBar`.
@@ -163,19 +169,19 @@ npm run start
```
:::info Check your doc
-- [ ] Whether the **look and feel** meet expectation?
-- [ ] Whether the **link/pictures** work fine?
+- [ ] Whether the **look and feel** meet expectations?
+- [ ] Whether the **links/pictures** work fine?
- [ ] Whether the important info is properly **highlighted**? [How to highlight?](#highlight_paragraph)
- [ ] Whether the **title levels** follow the [heading guide](#heading_level)?
:::
#### Step 5: Create a pull request
-When everything looks fine, create a pull request to the [kylin doc5.0 branch](https://github.com/apache/kylin/tree/doc5.0).
+When everything looks fine, create a pull request to the [Kylin doc5.0 branch](https://github.com/apache/kylin/tree/doc5.0).
:::note What, Pull Request?
For those who are new to pull requests, here it is explained.
-- How to geek -- [What are git pull requests](https://www.howtogeek.com/devops/what-are-git-pull-requests-and-how-do-you-use-them/)
+- How to geek -- [What is git pull requests](https://www.howtogeek.com/devops/what-are-git-pull-requests-and-how-do-you-use-them/)
- Github -- [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
:::
@@ -187,17 +193,17 @@ For those who are new to pull requests, here it is explained.
[Docusaurus](https://docusaurus.io/) is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).
-Apache Kylin's website and documentation is using [Docusaurus](https://docusaurus.io/) to manage and generate final content which avaliable at [http://kylin.apache.org](http://kylin.apache.org).
+Apache Kylin's website and documentation is using [Docusaurus](https://docusaurus.io/) to manage and generate final content which is available at [http://kylin.apache.org](http://kylin.apache.org).
-#### Kylin document structure and navigation menu
+#### Kylin's document structure and the navigation menu
The Kylin [website material](https://github.com/apache/kylin/tree/doc5.0) is maintained under the `doc5.0` branch.
1. __Home Page__: Home page of Docs
2. __Document__: General docs about Apache Kylin, including _Installation_, _Tutorial_, etc.
-3. __Development__: _"development"_ For developer to contribute, to develop, integration with other application and extend Apache Kylin
+3. __Development__: _"development"_ For the developer to contribute, develop, integrate with other applications and extend Apache Kylin
4. __Download__: _"Download"_ Apache Kylin packages
-5. __Community__: Apache kylin Community information
+5. __Community__: Apache Kylin Community information
6. __Blog__: Engineering blogs about Apache Kylin
#### Full doc structure
@@ -257,16 +263,16 @@ doc5.0
│ ├── ...
```
-More details about structure which managed by Docusaurus, please refer to [Project structure rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
+For more details about the structure which is managed by Docusaurus, please refer to the [Project structure rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
#### <span id="heading_level">Title/Heading Level</span>
-Here is [official guide about heading](https://docusaurus.io/docs/markdown-features/toc#markdown-headings). Please use level 3 title("###") and level 4 title("####") in most of the article.
+Here is the [official guide about heading](https://docusaurus.io/docs/markdown-features/toc#markdown-headings). Please use the level 3 title("###") and level 4 title("####") in most of the article.
Following is a general guide:
-- Use level 2 heading(aka "##") as **top level** title. The number of top level title should not more than two.
-- Use level 3 heading(aka "###") as **middle level** title.
-- Use level 4 heading(aka "####") as **the lowest level** title.
+- Use the level 2 heading(aka "##") as the **top-level** title. The number of top-level titles should not be more than two.
+- Use the level 3 heading(aka "###") as a **middle-level** title.
+- Use the level 4 heading(aka "####") as **the lowest level** title.
We recommend you to check for [this article](how_to_contribute) for example. Following is toc of it.
@@ -288,22 +294,22 @@ We recommend you to check for [this article](how_to_contribute) for example. Fol
#### Sidebar
The Sidebar is managed by __sidebars.js__ , please refer to [Sidebar](https://docusaurus.io/docs/sidebar).
-#### How to add image in doc
-All image should be put under _images_ folder, in your document, please using below sample to include image:
+#### How to add an image in a doc
+All images should be put under the _images_ folder, in your document, please use the below sample to include the image:
```
```
#### How to link to another page
-Using relative path for site links, check this [Markdown links](https://docusaurus.io/docs/markdown-features/links)
+Using relative path for site links, check this [Markdown link](https://docusaurus.io/docs/markdown-features/links)
#### How to add source code in doc
-We are using [Code Block](https://docusaurus.io/docs/markdown-features/code-blocks) to highlight code syntax, check this doc for more detail sample.
+We are using [Code Block](https://docusaurus.io/docs/markdown-features/code-blocks) to highlight code syntax, check this doc for a more detailed sample.
#### <span id="highlight_paragraph">How to highlight a sentence/paragraph</span>
-We recommend you to use [admonitions feature](https://docusaurus.io/docs/markdown-features/admonitions) to highlight a sentence/paragraph, following is a example:
+We recommend you use the [admonitions feature](https://docusaurus.io/docs/markdown-features/admonitions) to highlight a sentence/paragraph, following is an example:
```
:::caution