This is an automated email from the ASF dual-hosted git repository.
chengpan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/kyuubi.git
The following commit(s) were added to refs/heads/master by this push:
new 5032901df [KYUUBI #4768] [INFRA] Guidelines for Document and Code
contributions
5032901df is described below
commit 5032901dfc1a0b2762fe93244433e598ce997603
Author: Kent Yao <[email protected]>
AuthorDate: Thu Apr 27 19:58:10 2023 +0800
[KYUUBI #4768] [INFRA] Guidelines for Document and Code contributions
### _Why are the changes needed?_
Guidelines for Document and Code Contributions.
- code style
- documentation style
- quick starts
- sphinx-copybutton for copy button in code blocks
- add kind:minor,help wanted,good first issue to doc issue template
### _How was this patch tested?_
- [ ] Add some test cases that check the changes thoroughly including
negative and positive cases if possible
- [x] Add screenshots for manual tests if appropriate
<img width="1325" alt="image"
src="https://user-images.githubusercontent.com/8326978/234193368-473e2a1d-2deb-4d91-901a-19cea58a489b.png";>
- [x] [Run
test](https://kyuubi.readthedocs.io/en/master/develop_tools/testing.html#running-tests)
locally before make a pull request
Closes #4768 from yaooqinn/guide.
Closes #4768
3a0bd395b [Kent Yao] Update docs/contributing/doc/build.rst
8fe4f6d14 [Kent Yao] Update docs/contributing/doc/build.rst
a753bdde5 [Kent Yao] Guidelines for Document and Code contributions
f8393fe8d [Kent Yao] Guidelines for Document and Code contributions
8f2d3ce82 [Kent Yao] Guidelines for Document and Code contributions
4f3a2128b [Kent Yao] Guidelines for Document and Code contributions
Authored-by: Kent Yao <[email protected]>
Signed-off-by: Cheng Pan <[email protected]>
---
...oc-improvement-report.yml => documentation.yml} | 49 +++-----
docs/conf.py | 2 +
.../code}/building.md | 12 +-
.../code}/debugging.md | 2 +-
.../code}/developer.md | 10 --
.../code}/distribution.md | 2 +-
docs/contributing/code/get_started.rst | 70 +++++++++++
.../code}/idea_setup.md | 0
.../{develop_tools => contributing/code}/index.rst | 10 +-
docs/contributing/code/style.rst | 39 ++++++
.../code}/testing.md | 0
docs/contributing/doc/build.rst | 96 +++++++++++++++
docs/contributing/doc/get_started.rst | 117 ++++++++++++++++++
docs/contributing/doc/index.rst | 44 +++++++
docs/contributing/doc/style.rst | 135 +++++++++++++++++++++
docs/develop_tools/build_document.md | 76 ------------
docs/index.rst | 8 +-
docs/requirements.txt | 2 +
18 files changed, 545 insertions(+), 129 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/doc-improvement-report.yml
b/.github/ISSUE_TEMPLATE/documentation.yml
similarity index 67%
rename from .github/ISSUE_TEMPLATE/doc-improvement-report.yml
rename to .github/ISSUE_TEMPLATE/documentation.yml
index 668ddb256..87b87a6cd 100644
--- a/.github/ISSUE_TEMPLATE/doc-improvement-report.yml
+++ b/.github/ISSUE_TEMPLATE/documentation.yml
@@ -15,16 +15,11 @@
# limitations under the License.
#
-name: Doc Improvement Report
-title: "[DOCS] "
+name: Documentation fixes or improvement
+title: ":memo: Fix/Add <what> for <which> page"
description: Fix errors, or improve the content or refactor architecture of
online documentation
-labels: ["kind:documentation"]
+labels: ["kind:documentation,kind:minor,help wanted,good first issue"]
body:
- - type: markdown
- attributes:
- value: |
- Thank you for finding the time to report the problem! We really
appreciate the community efforts to improve Kyuubi.
-
- type: checkboxes
attributes:
label: Code of Conduct
@@ -43,22 +38,25 @@ body:
issues.
required: true
- - type: textarea
+ - type: dropdown
+ id: priority
attributes:
- label: Which parts of the documentation do you think need improvement?
- description: Please describe the details with documentation you have.
- placeholder: >
- Please include links to the documentation that you want to improve and
possibly screenshots showing
- the details. Explain why do you think it needs to improve. Make sure
you include view of the target
- audience of the documentation. Please explain why you think the docs
are wrong.
+ label: What type of changes will we make to the documentation?
+ options:
+ - Bugfixes
+ - Usage of New Feature
+ - Showcase
+ - Refactoring
+ - Typo, layout, grammar, spelling, punctuation errors, etc.
+ validations:
+ required: true
- type: input
id: versions
attributes:
label: Affects Version(s)
description: Which versions of Kyuubi Documentation are affected by this
issue?
- placeholder: >
- e.g. master/1.5.0/1.4.1/...
+ placeholder: e.g. master/1.5.0/1.4.1/...
validations:
required: true
@@ -67,20 +65,9 @@ body:
label: Improving the documentation
description: How do you think the documentation can be improved?
placeholder: >
- Please explain how you think the documentation could be improved.
Ideally specify where a new or missing
- documentation should be added and what kind of information should be
included. Sometimes people
- writing the documentation do not realise that some assumptions they
have might not be in the heads
- of the reader, so try to explain exactly what you would like to see in
the docs and why.
-
- - type: textarea
- attributes:
- label: Anything else
- description: Anything else we need to know?
- placeholder: >
- How often does this problem occur? (Once? Every time? Only when
certain conditions are met?)
- Any relevant logs to include? Put them here inside fenced
- ``` ``` blocks or inside a foldable details tag if it's long:
- <details><summary>x.log</summary> lots of stuff </details>
+ Please include links to the documentation that you want to improve and
possibly screenshots showing
+ the details. Explain why do you think it needs to improve. Make sure
you include view of the target
+ audience of the documentation. Please explain why you think the docs
are wrong.
- type: checkboxes
attributes:
diff --git a/docs/conf.py b/docs/conf.py
index dcf038314..eaac1aced 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -77,9 +77,11 @@ extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.mathjax',
'recommonmark',
+ 'sphinx_copybutton',
'sphinx_markdown_tables',
'sphinx_togglebutton',
'notfound.extension',
+ 'sphinxemoji.sphinxemoji',
]
master_doc = 'index'
diff --git a/docs/develop_tools/building.md b/docs/contributing/code/building.md
similarity index 93%
rename from docs/develop_tools/building.md
rename to docs/contributing/code/building.md
index d4582dc8d..8c5c5aeec 100644
--- a/docs/develop_tools/building.md
+++ b/docs/contributing/code/building.md
@@ -15,9 +15,9 @@
- limitations under the License.
-->
-# Building Kyuubi
+# Building From Source
-## Building Kyuubi with Apache Maven
+## Building With Maven
**Kyuubi** is built based on [Apache Maven](https://maven.apache.org),
@@ -33,7 +33,7 @@ If you want to test it manually, you can start Kyuubi
directly from the Kyuubi p
bin/kyuubi start
```
-## Building a Submodule Individually
+## Building A Submodule Individually
For instance, you can build the Kyuubi Common module using:
@@ -49,7 +49,7 @@ For instance, you can build the Kyuubi Common module using:
build/mvn clean package -pl kyuubi-common,kyuubi-ha -DskipTests
```
-## Skipping Some modules
+## Skipping Some Modules
For instance, you can build the Kyuubi modules without Kyuubi Codecov and
Assembly modules using:
@@ -57,7 +57,7 @@ For instance, you can build the Kyuubi modules without Kyuubi
Codecov and Assemb
mvn clean install -pl '!dev/kyuubi-codecov,!kyuubi-assembly' -DskipTests
```
-## Building Kyuubi against Different Apache Spark versions
+## Building Kyuubi Against Different Apache Spark Versions
Since v1.1.0, Kyuubi support building with different Spark profiles,
@@ -67,7 +67,7 @@ Since v1.1.0, Kyuubi support building with different Spark
profiles,
| -Pspark-3.2 | No | 1.4.0 |
| -Pspark-3.3 | Yes | 1.6.0 |
-## Building with Apache dlcdn site
+## Building With Apache dlcdn Site
By default, we use `https://archive.apache.org/dist/` to download the built-in
release packages of engines,
such as Spark or Flink.
diff --git a/docs/develop_tools/debugging.md
b/docs/contributing/code/debugging.md
similarity index 98%
rename from docs/develop_tools/debugging.md
rename to docs/contributing/code/debugging.md
index faf7173e4..d3fb6d16f 100644
--- a/docs/develop_tools/debugging.md
+++ b/docs/contributing/code/debugging.md
@@ -35,7 +35,7 @@ In the IDE, you set the corresponding parameters(host&port)
in debug configurati
<div align=center>
-
+
</div>
diff --git a/docs/develop_tools/developer.md
b/docs/contributing/code/developer.md
similarity index 91%
rename from docs/develop_tools/developer.md
rename to docs/contributing/code/developer.md
index 329e219de..8b52057e8 100644
--- a/docs/develop_tools/developer.md
+++ b/docs/contributing/code/developer.md
@@ -24,16 +24,6 @@
build/mvn versions:set -DgenerateBackupPoms=false
```
-## Update Document Version
-
-Whenever project version updates, please also update the document version at
`docs/conf.py` to target the upcoming release.
-
-For example,
-
-```python
-release = '1.2.0'
-```
-
## Update Dependency List
Kyuubi uses the `dev/dependencyList` file to indicate what upstream
dependencies will actually go to the server-side classpath.
diff --git a/docs/develop_tools/distribution.md
b/docs/contributing/code/distribution.md
similarity index 98%
rename from docs/develop_tools/distribution.md
rename to docs/contributing/code/distribution.md
index 217f0a417..23c9c6542 100644
--- a/docs/develop_tools/distribution.md
+++ b/docs/contributing/code/distribution.md
@@ -15,7 +15,7 @@
- limitations under the License.
-->
-# Building a Runnable Distribution
+# Building A Runnable Distribution
To create a Kyuubi distribution like those distributed by [Kyuubi Release
Page](https://kyuubi.apache.org/releases.html),
and that is laid out to be runnable, use `./build/dist` in the project root
directory.
diff --git a/docs/contributing/code/get_started.rst
b/docs/contributing/code/get_started.rst
new file mode 100644
index 000000000..33981a8cd
--- /dev/null
+++ b/docs/contributing/code/get_started.rst
@@ -0,0 +1,70 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+Get Started
+===========
+
+Good First Issues
+-----------------
+
+.. image::
https://img.shields.io/github/issues/apache/kyuubi/good%20first%20issue?color=green&label=Good%20first%20issue&logo=gfi&logoColor=red&style=for-the-badge
+ :alt: GitHub issues by-label
+ :target: `Good First Issues`_
+
+**Good First Issue** is initiative to curate easy pickings for first-time
+contributors. It helps you locate suitable development tasks with beginner's
+skills required, and finally make your first contribution to Kyuubi.
+
+After solving one or more good first issues, you should be able to
+
+- Find efficient ways to communicate with the community and get help
+- Setup `develop environment`_ on your machine
+- `Build`_ Kyuubi from source
+- `Run tests`_ locally
+- `Submit a pull request`_ through Github
+- Be listed in `Apache Kyuubi contributors`_
+- And most importantly, you can move to the next level and try some tricky
issues
+
+.. note:: Don't linger too long at this stage.
+ :class: dropdown, toggle
+
+Help Wanted Issues
+------------------
+
+.. image::
https://img.shields.io/github/issues/apache/kyuubi/help%20wanted?color=brightgreen&label=HELP%20WANTED&style=for-the-badge
+ :alt: GitHub issues by-label
+ :target: `Help Wanted Issues`_
+
+Issues that maintainers labeled as help wanted are mostly
+
+- sub-tasks of an ongoing shorthanded umbrella
+- non-urgent improvements
+- bug fixes for corner cases
+- feature requests not covered by current technology stack of kyuubi community
+
+Since these problems are not urgent, you can take your time when fixing them.
+
+.. note:: Help wanted issues may contain easy pickings and tricky ones.
+ :class: dropdown, toggle
+
+
+.. _Good First Issues:
https://github.com/apache/kyuubi/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
+.. _develop environment: idea_setup.html
+.. _Build: build.html
+.. _Run tests: testing.html
+.. _Submit a pull request: https://kyuubi.apache.org/pull_request.html
+.. _Apache Kyuubi contributors:
https://github.com/apache/kyuubi/graphs/contributors
+.. _Help Wanted Issues:
https://github.com/apache/kyuubi/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
+
diff --git a/docs/develop_tools/idea_setup.md
b/docs/contributing/code/idea_setup.md
similarity index 100%
rename from docs/develop_tools/idea_setup.md
rename to docs/contributing/code/idea_setup.md
diff --git a/docs/develop_tools/index.rst b/docs/contributing/code/index.rst
similarity index 84%
rename from docs/develop_tools/index.rst
rename to docs/contributing/code/index.rst
index c56321cb3..25a6e421b 100644
--- a/docs/develop_tools/index.rst
+++ b/docs/contributing/code/index.rst
@@ -13,15 +13,19 @@
See the License for the specific language governing permissions and
limitations under the License.
-Develop Tools
-=============
+Contributing Code
+=================
+
+These sections explain the process, guidelines, and tools for contributing
+code to the Kyuubi project.
.. toctree::
:maxdepth: 2
+ get_started
+ style
building
distribution
- build_document
testing
debugging
developer
diff --git a/docs/contributing/code/style.rst b/docs/contributing/code/style.rst
new file mode 100644
index 000000000..d967e8959
--- /dev/null
+++ b/docs/contributing/code/style.rst
@@ -0,0 +1,39 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+Code Style Guide
+================
+
+Code is written once by its author, but read and modified multiple times by
+lots of other engineers. As most bugs actually come from future modification
+of the code, we need to optimize our codebase for long-term, global
+readability and maintainability. The best way to achieve this is to write
+simple code.
+
+Kyuubi's source code is multilingual, specific code style will be applied to
+corresponding language.
+
+Scala Coding Style Guide
+------------------------
+
+Kyuubi adopts the `Databricks Scala Coding Style Guide`_ for scala codes.
+
+Java Coding Style Guide
+-----------------------
+
+Kyuubi adopts the `Google Java style`_ for java codes.
+
+.. _Databricks Scala Coding Style Guide:
https://github.com/databricks/scala-style-guide
+.. _Google Java style: https://google.github.io/styleguide/javaguide.html
\ No newline at end of file
diff --git a/docs/develop_tools/testing.md b/docs/contributing/code/testing.md
similarity index 100%
rename from docs/develop_tools/testing.md
rename to docs/contributing/code/testing.md
diff --git a/docs/contributing/doc/build.rst b/docs/contributing/doc/build.rst
new file mode 100644
index 000000000..4ec2362f3
--- /dev/null
+++ b/docs/contributing/doc/build.rst
@@ -0,0 +1,96 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+Building Documentation
+======================
+
+Follow the steps below and learn how to build the Kyuubi documentation as the
+one you are watching now.
+
+Setup Environment
+-----------------
+
+- Firstly, install ``virtualenv``, this is optional but recommended as it is
useful
+ to create an independent environment to resolve dependency issues for
building
+ the documentation.
+
+.. code-block:: sh
+ :caption: Install virtualenv
+
+ $ pip install virtualenv
+
+- Switch to the ``docs`` root directory.
+
+.. code-block:: sh
+ :caption: Switch to docs
+
+ $ cd $KYUUBI_SOURCE_PATH/docs
+
+- Create a virtual environment named 'kyuubi' or anything you like using
``virtualenv``
+ if it's not existing.
+
+.. code-block:: sh
+ :caption: New virtual environment
+
+ $ virtualenv kyuubi
+
+- Activate the virtual environment,
+
+.. code-block:: sh
+ :caption: Activate virtual environment
+
+ $ source ./kyuubi/bin/activate
+
+Install All Dependencies
+------------------------
+
+Install all dependencies enumerated in the ``requirements.txt``.
+
+.. code-block:: sh
+ :caption: Install dependencies
+
+ $ pip install -r requirements.txt
+
+
+Create Documentation
+--------------------
+
+Make sure you are in the ``$KYUUBI_SOURCE_PATH/docs`` directory.
+
+Linux & MacOS
+~~~~~~~~~~~~~
+
+.. code-block:: sh
+ :caption: Sphinx build on Unix-like OS
+
+ $ make html
+
+Windows
+~~~~~~~
+
+.. code-block:: sh
+ :caption: Sphinx build on Windows
+
+ $ make.bat html
+
+
+If the build process succeed, the HTML pages are in
+``$KYUUBI_SOURCE_PATH/docs/_build/html``.
+
+View Locally
+------------
+
+Open the `$KYUUBI_SOURCE_PATH/docs/_build/html/index.html` file in your
+favorite web browser.
diff --git a/docs/contributing/doc/get_started.rst
b/docs/contributing/doc/get_started.rst
new file mode 100644
index 000000000..f262695b7
--- /dev/null
+++ b/docs/contributing/doc/get_started.rst
@@ -0,0 +1,117 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+Get Started
+===========
+
+.. image::
https://img.shields.io/github/issues/apache/kyuubi/kind:documentation?color=green&logo=gfi&logoColor=red&style=for-the-badge
+ :alt: GitHub issues by-label
+
+
+Trivial Fixes
+-------------
+
+For typos, layout, grammar, spelling, punctuation errors and other similar
issues
+or changes that occur within a single file, it is acceptable to make edits
directly
+on the page being viewed. When viewing a source file on kyuubi's
+`Github repository`_, a simple click on the ``edit icon`` or keyboard shortcut
+``e`` will activate the editor. Similarly, when viewing files on `Read The
Docs`_
+platform, clicking on the ``suggest edit`` button will lead you to the editor.
+These methods do not require any local development environment setup and
+are convenient for making quick fixes.
+
+Upon completion of the editing process, opt the ``commit changes`` option,
+adhere to the provided instructions to submit a pull request,
+and await feedback from the designated reviewer.
+
+Major Fixes
+-----------
+
+For significant modifications that affect multiple files, it is advisable to
+clone the repository to a local development environment, implement the
necessary
+changes, and conduct thorough testing prior to submitting a pull request.
+
+
+`Fork`_ The Repository
+~~~~~~~~~~~~~~~~~~~~~~
+
+Clone The Forked Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+ :caption: Clone the repository
+
+ $ git clone https://github.com/your_username/kyuubi.git
+
+Replace "your_username" with your GitHub username. This will create a local
+copy of your forked repository on your machine. You will see the ``master``
+branch if you run ``git branch`` in the ``kyuubi`` folder.
+
+Create A New Branch
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+ :caption: Create a new branch
+
+ $ git checkout -b guide
+ Switched to a new branch 'guide'
+
+Editing And Testing
+~~~~~~~~~~~~~~~~~~~
+
+Make the necessary changes to the documentation files using a text editor.
+`Build and verify`_ the changes you have made to see if they look fine.
+
+.. note::
+ :class: dropdown, toggle
+
+Create A Pull Request
+~~~~~~~~~~~~~~~~~~~~~
+
+Once you have made the changes,
+
+- Commit them with a descriptive commit message using the command:
+
+.. code-block::
+ :caption: commit the changes
+
+ $ git commit -m "Description of changes made"
+
+- Push the changes to your forked repository using the command
+
+.. code-block::
+ :caption: push the changes
+
+ $ git push origin guide
+
+- `Create A Pull Request`_ with a descriptive PR title and description.
+
+- Polishing the PR with comments of reviews addressed
+
+Report Only
+-----------
+
+If you don't have time to fix the doc issue and submit a pull request on your
own,
+`reporting a document issue`_ also helps. Please follow some basic rules:
+
+- Use the title field to clearly describe the issue
+- Choose the documentation report template
+- Fill out the required field in the documentation report
+
+.. _Home Page: https://kyuubi.apache.org
+.. _Fork: https://github.com/apache/kyuubi/fork
+.. _Build and verify: build.html
+.. _Create A Pull Request:
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+.. _reporting a document issue:
https://github.com/apache/kyuubi/issues/new/choose
\ No newline at end of file
diff --git a/docs/contributing/doc/index.rst b/docs/contributing/doc/index.rst
new file mode 100644
index 000000000..bf6ae41bd
--- /dev/null
+++ b/docs/contributing/doc/index.rst
@@ -0,0 +1,44 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+Contributing Documentations
+===========================
+
+The project documentation is crucial for users and contributors. This guide
+outlines the contribution guidelines for Apache Kyuubi documentation.
+
+Kyuubi's documentation source files are maintained in the same `github
repository`_
+as the code base, which ensures updating code and documentation synchronously.
+All documentation source files can be found in the sub-folder named ``docs``.
+
+Kyuubi's documentation is published and hosted on `Read The Docs`_ platform by
+version. with each version having its own dedicated page. To access a specific
+version of the document, simply navigate to the "Docs" tab on our Home Page.
+
+We welcome any contributions to the documentation, including but not limited to
+writing, translation, report doc issues on Github, reposting.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ get_started
+ style
+ build
+
+.. _Github repository: https://github.com/apache/kyuubi
+.. _Restructured Text: https://en.wikipedia.org/wiki/ReStructuredText
+.. _Read The Docs: https://kyuubi.rtfd.io
+.. _Home Page: https://kyuubi.apache.org
\ No newline at end of file
diff --git a/docs/contributing/doc/style.rst b/docs/contributing/doc/style.rst
new file mode 100644
index 000000000..14cc2b8ac
--- /dev/null
+++ b/docs/contributing/doc/style.rst
@@ -0,0 +1,135 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+Documentation Style Guide
+=========================
+
+This guide contains guidelines, not rules. While guidelines are important
+to follow, they are not hard and fast rules. It's important to use your
+own judgement and discretion when creating content, and to depart from the
+guidelines when necessary to improve the quality and effectiveness of your
+content. Ultimately, the goal is to create content that is clear, concise,
+and useful to your audience, and sometimes deviating from the guidelines
+may be necessary to achieve that goal.
+
+Goals
+-----
+
+- Source text files are readable and portable
+- Source diagram files are editable
+- Source files are maintainable over time and across community
+
+License Header
+--------------
+
+All original documents should include the ASF license header. All reproduced
+or quoted content should be authorized and attributed to the source.
+
+If you are about to quote some from commercial materials, please refer to
+`ASF 3RD PARTY LICENSE POLICY`_, or consult the Apache Kyuubi PMC to avoid
+legality issues.
+
+General Style
+-------------
+
+- Use `ReStructuredText`_ or `Markdown`_ format for text, avoid HTML hacks
+- Use `draw.io`_ for drawing or editing an image, and export it as PNG for
+ referencing in document. A pull request should commit both of them
+- Use Kyuubi for short instead of Apache Kyuubi after the first time in the
+ same page
+- Character line limit: 78, except unbreakable ones
+- Prefer lists to tables
+- Prefer unordered list than ordered
+
+ReStructuredText
+----------------
+
+Headings
+~~~~~~~~
+
+- Use **Pascal Case**, every word starts with an uppercase letter,
+ e.g., 'Documentation Style Guide'
+- Use a max of **three levels**
+ - Split into multiple files when there comes an H4
+ - Prefer `directive rubric`_ than H4
+- Use underline-only adornment styles, **DO NOT** use overline
+ - The length of underline characters **SHOULD** match the title
+ - H1 should be underlined with '='
+ - H2 should be underlined with '-'
+ - H3 should be underlined with '~'
+ - H4 should be underlined with '^', but it's better to avoid using H4
+- **DO NOT** use numbering for sections
+- **DO NOT** use "Kyuubi" in titles if possible
+
+Links
+~~~~~
+
+- Define links with short descriptive phrases, group them at the bottom of the
file
+
+.. note::
+ :class: dropdown, toggle
+
+ .. code-block::
+ :caption: Recommended
+
+ Please refer to `Apache Kyuubi Home Page`_.
+
+ .. _Apache Kyuubi Home Page: https://kyuubi.apache.org/
+
+ .. code-block::
+ :caption: Not recommended
+
+ Please refer to `Apache Kyuubi Home Page <https://kyuubi.apache.org/>`_.
+
+
+Markdown
+--------
+
+Headings
+~~~~~~~~
+
+- Use **Pascal Case**, every word starts with an uppercase letter,
+ e.g., 'Documentation Style Guide'
+- Use a max of **three levels**
+ - Split into multiple files when there comes an H4
+- **DO NOT** use numbering for sections
+- **DO NOT** use "Kyuubi" in titles if possible
+
+Images
+------
+
+Use images only when they provide helpful visual explanations of information
+otherwise difficult to express with words
+
+Third-party references
+----------------------
+
+If the preceding references don't provide explicit guidance, then see these
+third-party references, depending on the nature of your question:
+
+- `Google developer documentation style`_
+- `Apple Style Guide`_
+- `Red Hat supplementary style guide for product documentation`_
+
+.. References
+
+.. _ASF 3RD PARTY LICENSE POLICY:
https://www.apache.org/legal/resolved.html#asf-3rd-party-license-policy
+.. _directive rubric
:https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-rubric
+.. _ReStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+.. _draw.io: https://www.diagrams.net/
+.. _Google developer documentation style: https://developers.google.com/style
+.. _Apple Style Guide: https://help.apple.com/applestyleguide/
+.. _Red Hat supplementary style guide for product documentation:
https://redhat-documentation.github.io/supplementary-style-guide/
diff --git a/docs/develop_tools/build_document.md
b/docs/develop_tools/build_document.md
deleted file mode 100644
index 0be5a1807..000000000
--- a/docs/develop_tools/build_document.md
+++ /dev/null
@@ -1,76 +0,0 @@
-<!--
-- Licensed to the Apache Software Foundation (ASF) under one or more
-- contributor license agreements. See the NOTICE file distributed with
-- this work for additional information regarding copyright ownership.
-- The ASF licenses this file to You under the Apache License, Version 2.0
-- (the "License"); you may not use this file except in compliance with
-- the License. You may obtain a copy of the License at
--
-- http://www.apache.org/licenses/LICENSE-2.0
--
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.
--->
-
-# Building Kyuubi Documentation
-
-Follow the steps below and learn how to build the Kyuubi documentation as the
one you are watching now.
-
-## Install & Activate `virtualenv`
-
-Firstly, install `virtualenv`, this is optional but recommended as it is
useful to create an independent environment to resolve dependency issues for
building the documentation.
-
-```bash
-pip install virtualenv
-```
-
-Switch to the `docs` root directory.
-
-```bash
-cd $KYUUBI_SOURCE_PATH/docs
-```
-
-Create a virtual environment named 'kyuubi' or anything you like using
`virtualenv` if it's not existing.
-
-```bash
-virtualenv kyuubi
-```
-
-Activate it,
-
-```bash
-source ./kyuubi/bin/activate
-```
-
-## Install all dependencies
-
-Install all dependencies enumerated in the `requirements.txt`.
-
-```bash
-pip install -r requirements.txt
-```
-
-## Create Documentation
-
-Make sure you are in the `$KYUUBI_SOURCE_PATH/docs` directory.
-
-linux & macos
-
-```bash
-make html
-```
-
-windows
-
-```bash
-make.bat html
-```
-
-If the build process succeed, the HTML pages are in
`$KYUUBI_SOURCE_PATH/docs/_build/html`.
-
-## View Locally
-
-Open the `$KYUUBI_SOURCE_PATH/docs/_build/html/index.html` file in your
favorite web browser.
diff --git a/docs/index.rst b/docs/index.rst
index fbd299e7b..7f6e0a248 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -216,7 +216,13 @@ What's Next
:caption: Contributing
:maxdepth: 2
- develop_tools/index
+ contributing/code/index
+ contributing/doc/index
+
+.. toctree::
+ :caption: Community
+ :maxdepth: 2
+
community/index
.. toctree::
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ecc8116e7..8e1f5c471 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -24,3 +24,5 @@ sphinx-book-theme==0.3.3
sphinx-markdown-tables==0.0.17
sphinx-notfound-page==0.8.3
sphinx-togglebutton===0.3.2
+sphinxemoji===0.2.0
+sphinx-copybutton===0.5.2
![https://user-images.githubusercontent.com/8326978/234193368-473e2a1d-2deb-4d91-901a-19cea58a489b.png"](https://user-images.githubusercontent.com/8326978/234193368-473e2a1d-2deb-4d91-901a-19cea58a489b.png"){kind=link}