5032901dfc
### _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 <yao@apache.org> Signed-off-by: Cheng Pan <chengpan@apache.org>
136 lines
4.7 KiB
ReStructuredText
136 lines
4.7 KiB
ReStructuredText
.. 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/
|