c31c1a5925
### Why are the changes needed? The PR fixes few `Unknown target name: "XYZ". [docutils]` issues and resolves the following errors messages: ``` ../kyuubi/docs/contributing/doc/get_started.rst:27: ERROR: Unknown target name: "github repository". [docutils] ../kyuubi/docs/contributing/doc/get_started.rst:27: ERROR: Unknown target name: "read the docs". [docutils] ../kyuubi/docs/contributing/doc/style.rst:66: ERROR: Unknown target name: "directive rubric". [docutils] ``` ### How was this patch tested? Built documentation locally, checked there are no related error messages and doc pages are correct. ##### Page `contributing/doc/get_started.html` Before changes <img width="1114" alt="image" src="https://github.com/user-attachments/assets/f1a19c51-3c4c-4268-bf83-7ca0c60315b1" /> After changes <img width="1113" alt="image" src="https://github.com/user-attachments/assets/437edef1-0fd9-43bf-bd3f-bda43035a2c9" /> ##### Page `contributing/doc/style.html` Before changes <img width="1128" alt="image" src="https://github.com/user-attachments/assets/39666841-1155-439f-9045-06a9d78624c3" /> After changes <img width="1117" alt="image" src="https://github.com/user-attachments/assets/2e1f8663-5c1e-4a3c-887e-5f65d01b4cf3" /> ### Was this patch authored or co-authored using generative AI tooling? No Closes #6987 from dnskr/fix-doc-unknown-target-name. Closes #6987 391958b4d [dnskr] [DOC] Fix Unknown target name issues Authored-by: dnskr <dnskrv88@gmail.com> Signed-off-by: Cheng Pan <chengpan@apache.org>
118 lines
4.2 KiB
ReStructuredText
118 lines
4.2 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.
|
|
|
|
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
|
|
:target: `Documentation Issues`_
|
|
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
.. _Github repository: https://github.com/apache/kyuubi
|
|
.. _Read The Docs: https://kyuubi.rtfd.io
|
|
.. _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
|
|
.. _Documentation Issues: https://github.com/apache/kyuubi/issues?q=is%3Aopen+is%3Aissue+label%3Akind%3Adocumentation
|