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 <dethr...@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
