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 13787c5e5b9ac3c740b0151c847c5a68dccc01ba
Author: XiaoxiangYu <x...@apache.org>
AuthorDate: Thu Aug 25 14:25:35 2022 +0800
Refine some pages including how to add new doc, how to contribute
---
website/docs/development/how_to_contribute.md | 16 +-
website/docs/development/how_to_package.md | 6 +-
website/docs/development/how_to_write_doc.md | 228 ++++++++++-----------
.../development/images/how-to-write-doc-01.png | Bin 2043 -> 176990 bytes
4 files changed, 124 insertions(+), 126 deletions(-)
diff --git a/website/docs/development/how_to_contribute.md
b/website/docs/development/how_to_contribute.md
index 192306fa42..1b9a6097e8 100644
--- a/website/docs/development/how_to_contribute.md
+++ b/website/docs/development/how_to_contribute.md
@@ -20,8 +20,8 @@ Apache Kylin is always looking for contributions of not only
code, but also usag
## Source Branches
Both code and document are under Git source control. Note the purpose of
different branches.
-* `kylin5`: Development branch for a certain major release for v5.x
-* `doc5.0`: Document branch for V5.x
+* `kylin5`: Development branch for v5.x
+* `doc5.0`: Document branch for v5.x
* `main`: Maintenance branch for a certain major release for v4.x
* `2.[n].x`: Maintenance branch for a certain major release for v2.x
@@ -29,11 +29,7 @@ Both code and document are under Git source control. Note
the purpose of differe
* `document`: Document branch for V4.x and before
## Pick a task
-There are open tasks waiting to be done, tracked by JIRA. To make it easier to
search, there are a few JIRA filters.
-
-* [A list of tasks](https://issues.apache.org/jira/issues/?filter=12339895)
managed by Yang Li.
-* [A list of tasks](https://issues.apache.org/jira/issues/?filter=12341496)
opened by Ted Yu, important small bugs and some are easy fixes.
-* Also you can search for tag "newbie" in Kylin JIRA.
+There are open tasks waiting to be done, tracked by JIRA.
Do not forget to discuss in [mailing list](#TODO) before working on a big task.
@@ -76,13 +72,13 @@ git clone https://github.com/<YourUserName>/kylin.git
Once the repo is cloned, you need to do two things:
-1. Create a new branch by issuing the command:
+* Create a new branch by issuing the command:
```shell
git checkout -b new_branch
```
-2. Create a new remote for the upstream repo with the command:
+* Create a new remote for the upstream repo with the command:
```shell
git remote add upstream https://github.com/apache/kylin.git
@@ -135,4 +131,4 @@ Patches that span components need at least two +1s before
they can be committed,
Any -1 on a patch by anyone vetoes a patch; it cannot be committed until the
justification for the -1 is addressed.
## Making Document Changes
-Check out [How to Write Document](how_to_write_doc.md).
+Check out [How to Write Document](./how_to_write_doc).
diff --git a/website/docs/development/how_to_package.md
b/website/docs/development/how_to_package.md
index a52c95a8c0..dd3f86a186 100644
--- a/website/docs/development/how_to_package.md
+++ b/website/docs/development/how_to_package.md
@@ -64,7 +64,7 @@ For example, an unofficial package could be
`apache-kylin-5.0.0-SNAPSHOT.2022081
# and third party cannot be distributed because of apache distribution
policy(size and license)
./build/release/release.sh -noSpark -official
-## Case 3: A package for runing on Apache Hadoop 3 platform
+## Case 3: A package for Apache Hadoop 3 platform
./build/release/release.sh -P hadoop3
```
@@ -73,9 +73,11 @@ For example, an unofficial package could be
`apache-kylin-5.0.0-SNAPSHOT.2022081
If you install node.js which is higher than 14.X, I recommended you downgrade
to lower version with some tools like https://github.com/nvm-sh/nvm.
```shell
-## switch to specific version
+## Switch to specific version using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
nvm install 12.14.0
+
+## Before packaging, please switch to specific version
nvm use 12.14.0
## switch to original version
diff --git a/website/docs/development/how_to_write_doc.md
b/website/docs/development/how_to_write_doc.md
index 4cc53b45f9..7e4ceaf698 100644
--- a/website/docs/development/how_to_write_doc.md
+++ b/website/docs/development/how_to_write_doc.md
@@ -15,13 +15,11 @@ last_update:
date: 08/24/2022
---
-We write documents in MD format and convert to HTML using
[Docusaurus](https://docusaurus.io/). [Docusaurus](https://docusaurus.io/) is
essentially a set of npm
[packages](https://github.com/facebook/docusaurus/tree/main/packages).
+From Kylin 5.0, Kylin community proposed to write documents using
[Docusaurus](https://docusaurus.io/). Please note multi-version and
i18n(multi-language) is in our plan, so it is not supported right now.
-The [Docusaurus](https://docusaurus.io/) generated HTML gets uploaded to
apache SVN and becomes Kylin website. All MD source files are managed in git so
all changes and contributors are clearly tracked.
+### Shortcut: Edit a single existent page
-## Quick edit a page
-
-If you found some minor typos or mistakes on a page, you can quickly fix the
page and create a commit.
+If you found some minor typos or mistakes on a single page, you can quickly
commit the change without clone source code and preview in user's local machine.
Just scroll down the page to the bottom and click the `Edit this page`.
@@ -30,19 +28,19 @@ Just scroll down the page to the bottom and click the `Edit
this page`.
Edit the page.
-Create a commit.
+Raise a pull request.
-> Note: If you want to add documentation or some more changes, please do as
following steps.
+> Note: If you want to add NEW pages/upload images/change frontend style,
please do as following steps.
## Before your work
-Before you add or edit documentation, please deploy the document compilation
environment.
+Before you add new documentation, please deploy the document compilation
environment.
There are two steps:
- [Deploy a local document compilation environment](#Deploy)
-- [Download docs repo and configuration](#Download)
+- [Download repo](#Download)
### <span id="Deploy">Deploy a local document compilation environment</span>
@@ -57,7 +55,7 @@ Install following tools before you add or edit documentation:
2. And optionally any markdown editor you prefer
-### <span id="Download">Download docs repo and initialization</span>
+### <span id="Download">Download docs repo</span>
1. Download the doc repo to any path you prefer.
@@ -69,27 +67,120 @@ git clone --branch doc5.0
https://github.com/apache/kylin.git # Or git clone -b
2. After pre-step, install dependencies for prerequisite of doc.
```shell
-cd /path/to/repo/website
+cd website
npm install
```
-To check that initialization occurred successfully, run:
+To check if that environment works well, run:
```shell
npm run start
```
-then, a local website of `http://localhost:3000` will automatically open in
your default browser and no errors occurred.
+then, home page doc (`http://localhost:3000`) will automatically open in your
default browser and no errors occurred.
-## About [Docusaurus](https://docusaurus.io/)
+
+## How to create new document
+
+### Create a new markdown file
+
+Open doc with any markdown editor, draft content as following:
+
+```
+---
+title: Example doc
+language: en
+sidebar_label: Example doc
+pagination_label: Example doc
+toc_min_heading_level: 2
+toc_max_heading_level: 6
+pagination_prev: null
+pagination_next: null
+keywords:
+ - doc
+draft: false
+last_update:
+ date: 08/23/2022
+---
+
+## This is example doc
+The quick brown fox jump over the lazy dog.
+```
+
+> ***Note***:
+>
+> 1. Please note that every doc need the ___Head metadata___. More details
about `Head metadata` of a doc, please refer to [Head
metadata](https://docusaurus.io/docs/markdown-features/head-metadata).
+>
+> 2. Please use the template `Head metadata` in your modified doc.
+ ```shell
+ ---
+ title: Example doc
+ language: en
+ sidebar_label: Example doc
+ pagination_label: Example doc
+ toc_min_heading_level: 2
+ toc_max_heading_level: 6
+ pagination_prev: null
+ pagination_next: null
+ keywords:
+ - doc
+ draft: false
+ last_update:
+ date: 08/23/2022
+ ---
+ ```
+>
+> 3. Please use `second heading level` for the doc header start.
+
+
+### How to add a new page to the sidebar
+
+Add the `{}` doc side block in sideBars.
+
+Example:
+
+Scene: If you want to add the sidebar of `how_to_write_doc.md` to be the
children menu of `development`.
+
+Then, modify the `DevelopmentSideBar` block in sidebars.js and add a new block
in the `items` of `DevelopmentSideBar`.
+
+```shell
+DevelopmentSideBar: [
+ {
+ ...
+ items: [
+ {...},
+ ...,
+ {
+ type: 'doc',
+ id: 'development/how_to_write_doc.md'
+ },
+ ],
+ },
+],
+```
+
+
+### Preview in your local machine
+You can preview in your browser, to check exactly what it will look like,
please run following commands in the `website` directory of repo folder:
+
+```
+npm run start
+```
+Then access http://127.0.0.1:3000 in your browser.
+
+If everything is normal, create a pull request to [Apache Kylin
Repo](https://github.com/apache/kylin) and target branch is `doc5.0`.
+
+## Documentation Specification
+
+### About [Docusaurus](https://docusaurus.io/)
[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).
-## Kylin document structure and navigation menu
+### Kylin document structure and navigation menu
The Kylin [website as the Docusaurus
source](https://github.com/apache/kylin/tree/document/doc5.0) is maintained
under the `doc5.0` branch.
@@ -159,7 +250,7 @@ doc5.0
More details about structure which managed by Docusaurus, please refer to
[Project structure
rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
-### Navigation menu
+### Navigation menu
The menu is managed by Docusaurus collection:
@@ -167,112 +258,21 @@ The menu is managed by Docusaurus collection:
More details about sidebars in Docusaurus, please refer to
[Sidebar](https://docusaurus.io/docs/sidebar).
-## How to add a doc to the sidebar
-
-Add the `{}` doc side block in sideBars.
-
-Example:
-Scene: If you want to add the sidebar of `how_to_write_doc.md` to be the
children menu of `development`.
+### How to add image
+All image should be put under _images_ folder, in your document, please using
below sample to include image:
-Then, modify the `DevelopmentSideBar` block in sidebars.js and add a new block
in the `items` of `DevelopmentSideBar`.
-
-```shell
-DevelopmentSideBar: [
- {
- ...
- items: [
- {...},
- ...,
- {
- type: 'doc',
- id: 'development/how_to_write_doc.md'
- },
- ],
- },
-],
```
-
-
-## How to edit document
-Open doc with any markdown editor, draft content and preview in local.
-
-Sample Doc:
-
+
```
----
-title: Example doc
-language: en
-sidebar_label: Example doc
-pagination_label: Example doc
-toc_min_heading_level: 2
-toc_max_heading_level: 6
-pagination_prev: null
-pagination_next: null
-keywords:
- - doc
-draft: false
-last_update:
- date: 08/23/2022
----
-## This is example doc
-The quick brown fox jump over the lazy dog.
-```
-
-> ***Note***:
->
-> 1. Please note that every doc need the ___Head metadata___. More details
about `Head metadata` of a doc, please refer to [Head
metadata](https://docusaurus.io/docs/markdown-features/head-metadata).
->
-> 2. Please use the template `Head metadata` in your modified doc.
- ```shell
- ---
- title: Example doc
- language: en
- sidebar_label: Example doc
- pagination_label: Example doc
- toc_min_heading_level: 2
- toc_max_heading_level: 6
- pagination_prev: null
- pagination_next: null
- keywords:
- - doc
- draft: false
- last_update:
- date: 08/23/2022
- ---
- ```
->
-> 3. Please use `second heading level` for the doc header start.
-
-
-
-## How to add image
-All impage please put under _images_ folder, in your document, please using
below sample to include image:
-
-```
-
-```
-
-## How to add link
+### How to link to another page
Using relative path for site links, for example:
```
-[How To Write Docs](../development/how_to_write_doc.md).
-```
-
-## How to add code highlight
-We are using [Rouge](https://github.com/jneen/rouge) to highlight code syntax.
-check this doc's source code for more detail sample.
-
-
-## How to preview in your local
-You can preview in your markdown editor, to check exactly what it will looks
like on website, please run Docusaurus in the root of repo folder:
-
-```
-npm run start
+[How To Write Docs](../development/how_to_write_doc).
```
-Then access http://127.0.0.1:3000 in your browser.
-If everything is normal, create a pull request to [Apache Kylin
Repo](https://github.com/apache/kylin) and target branch is `doc5.0`.
+### How to add code highlight
+We are using [Rouge](https://github.com/jneen/rouge) to highlight code syntax,
check this doc for more detail sample.
diff --git a/website/docs/development/images/how-to-write-doc-01.png
b/website/docs/development/images/how-to-write-doc-01.png
index 227d6ccf88..3ea171bb23 100644
Binary files a/website/docs/development/images/how-to-write-doc-01.png and
b/website/docs/development/images/how-to-write-doc-01.png differ
