add(proposal): Added proposal for Kmesh website automation#1433
add(proposal): Added proposal for Kmesh website automation#1433kmesh-bot merged 13 commits intokmesh-net:mainfrom yashisrani:add/proposal
Conversation
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
|
@yashisrani: The label(s) DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
Welcome @yashisrani! It looks like this is your first PR to kmesh-net/kmesh 🎉 |
There was a problem hiding this comment.
Summary of Changes
Hello @yashisrani, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request introduces a comprehensive proposal aimed at significantly improving the Kmesh project's documentation workflow. It addresses current manual processes by outlining automated solutions for synchronizing kmeshctl documentation, managing versioned releases, and enhancing the quality of Chinese language content on the Kmesh website. The goal is to reduce manual effort, ensure consistency, and provide a more streamlined experience for both developers and users.
Highlights
- Proposal for Documentation Automation: This PR introduces a detailed proposal outlining strategies to automate the Kmesh project's website and documentation processes, addressing current manual workflows and inconsistencies.
- Kmeshctl Documentation Sync: Proposes solutions for automatically synchronizing
kmeshctldocumentation from the main repository to the Kmesh website, suggesting a dedicated script via GitHub Actions or a unified documentation repository approach. - Automated Doc Versioning: Details a workflow to automate documentation versioning and release, ensuring old versions are archived and new ones are published upon tag creation using Docusaurus.
- Chinese Documentation Quality: Includes a bonus proposal for implementing automated typo and grammar checks for Chinese documentation, leveraging tools like LanguageTool to enhance content quality.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
The pull request introduces a proposal for automating the Kmesh website documentation, including versioning and synchronization of kmeshctl docs. The proposal is well-structured, but there are several typos, grammatical errors, and areas where phrasing could be improved for clarity. The review comments focus on correcting these issues to enhance the readability and professionalism of the document.
| @@ -0,0 +1,223 @@ | |||
| --- | |||
| title: Proposal for Website automation and chinese docs optimization | |||
There was a problem hiding this comment.
The title has a capitalization issue. 'chinese' should be 'Chinese' for proper noun consistency.
| title: Proposal for Website automation and chinese docs optimization | |
| title: Proposal for Website automation and Chinese docs optimization |
|
|
||
| --- | ||
|
|
||
| ## Proposal for Website automation and chinese docs optimization |
There was a problem hiding this comment.
The heading has a capitalization issue. 'chinese' should be 'Chinese'.
| ## Proposal for Website automation and chinese docs optimization | |
| ## Proposal for Website automation and Chinese docs optimization |
| A good summary is probably at least a paragraph in length. | ||
| --> | ||
|
|
||
| - Currently, Kmesh project lacked good automation around website & documentation. We want to manually copy and paste documentation into a website. which often led to inconsistencies and duplicate effort across teams. When website was recently refactored, a new feature to archive old documents was added, but it still dependent on manual CLI steps during each release. |
There was a problem hiding this comment.
The sentence is lengthy and contains grammatical errors that affect readability. Rephrase for clarity and correctness.
| - Currently, Kmesh project lacked good automation around website & documentation. We want to manually copy and paste documentation into a website. which often led to inconsistencies and duplicate effort across teams. When website was recently refactored, a new feature to archive old documents was added, but it still dependent on manual CLI steps during each release. | |
| - Currently, the Kmesh project lacks effective automation for its website and documentation. Documentation is manually copied to the website, leading to inconsistencies and duplicated effort. A recent website refactor added a feature to archive old documents, but the process still relies on manual CLI steps during each release. |
|
|
||
| - Currently, Kmesh project lacked good automation around website & documentation. We want to manually copy and paste documentation into a website. which often led to inconsistencies and duplicate effort across teams. When website was recently refactored, a new feature to archive old documents was added, but it still dependent on manual CLI steps during each release. | ||
|
|
||
| - The chinese documentation lacking any automated checks for typos or grammatical errors. |
There was a problem hiding this comment.
The sentence has capitalization and verb tense issues: 'chinese' should be 'Chinese', and the verb tense of 'lacking' should be 'lacks'.
| - The chinese documentation lacking any automated checks for typos or grammatical errors. | |
| - The Chinese documentation lacks any automated checks for typos or grammatical errors. |
| this KEP. Describe why the change is important and the benefits to users. | ||
| --> | ||
|
|
||
| - Kmesh Previous workflows were manual & time consuming and new releases required repetitve manual step, wasting engineering time. |
There was a problem hiding this comment.
The sentence has typos ('repetitve' -> 'repetitive', 'time consuming' -> 'time-consuming') and could be phrased more clearly.
| - Kmesh Previous workflows were manual & time consuming and new releases required repetitve manual step, wasting engineering time. | |
| - Previous Kmesh workflows were manual and time-consuming, and new releases required repetitive manual steps, wasting engineering time. |
|
|
||
| - **Solution - 2** | ||
|
|
||
| - We can create a new folder which will contain all chinese documentation, then we can perform same typos/grammer checks using **LanguageTool**. in this case, There is no need to add a condition like (*-zh.md, *_CN.md). |
There was a problem hiding this comment.
The sentence has typos and grammatical issues. Consider this revised version for clarity.
| - We can create a new folder which will contain all chinese documentation, then we can perform same typos/grammer checks using **LanguageTool**. in this case, There is no need to add a condition like (*-zh.md, *_CN.md). | |
| - We can create a new folder that will contain all Chinese documentation. Then we can perform the same typo/grammar checks using **LanguageTool**. In this case, there would be no need to add a condition like (*-zh.md, *_CN.md). |
| **1. Github Actions for Sync:** | ||
| - Instead of Netlify-triggered script, use a Github Action to sync `kmesh/docs/ctl/` to `kmesh/website/docs` and commit directly. | ||
| - **Pros**: Unified Automation in Github, No Netlify Dependency. |
There was a problem hiding this comment.
For consistency with the brand name, 'Github' should be 'GitHub'.
| **1. Github Actions for Sync:** | |
| - Instead of Netlify-triggered script, use a Github Action to sync `kmesh/docs/ctl/` to `kmesh/website/docs` and commit directly. | |
| - **Pros**: Unified Automation in Github, No Netlify Dependency. | |
| **1. GitHub Actions for Sync:** | |
| - Instead of Netlify-triggered script, use a GitHub Action to sync `kmesh/docs/ctl/` to `kmesh/website/docs` and commit directly. | |
| - **Pros**: Unified Automation in GitHub, No Netlify Dependency. |
| **1. Github Actions for Sync:** | ||
| - Instead of Netlify-triggered script, use a Github Action to sync `kmesh/docs/ctl/` to `kmesh/website/docs` and commit directly. | ||
| - **Pros**: Unified Automation in Github, No Netlify Dependency. | ||
| - **Cons**: Required managing commits. |
There was a problem hiding this comment.
Typo: 'Required' should be 'Requires'.
| - **Cons**: Required managing commits. | |
| - **Cons**: Requires managing commits. |
| **2. Manual Versioning:** | ||
| - Manually run Docusaurus versioning commands instead of a workflow. | ||
| - **Pros**: Simpler initial setup. | ||
| - **Cons**: Required managing commits. |
There was a problem hiding this comment.
Typo: 'Required' should be 'Requires'.
| - **Cons**: Required managing commits. | |
| - **Cons**: Requires managing commits. |
| - Use APIs for advanced chinese typo/grammer checks. | ||
| - **Pros**: More accurate than LanguageTool for chinese. |
There was a problem hiding this comment.
The sentence has typos: 'chinese' should be 'Chinese' and 'grammer' should be 'grammar'.
| - Use APIs for advanced chinese typo/grammer checks. | |
| - **Pros**: More accurate than LanguageTool for chinese. | |
| - Use APIs for advanced Chinese typo/grammar checks. | |
| - **Pros**: More accurate than LanguageTool for Chinese. |
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
|
|
||
| - **Solution - 1 Script (`website/scripts/sync-kmeshctl-docs.sh`):** | ||
|
|
||
| - It clones `Kmesh-net/kmesh`, copies `docs/ctl/` to `website/docs/` , using Github action workflow. |
There was a problem hiding this comment.
You can add more implementation details, such as script content, to your proposal
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
| git -C website diff --staged --quiet && { echo "No changes to commit"; exit 0; } | ||
| git -C website commit -m "Sync kmeshctl docs from kmesh-net/kmesh" | ||
| git -C website push | ||
| echo "Synced kmeshctl docs to website/docs/kmeshctl/" |
There was a problem hiding this comment.
Prefer opeing up pr instead of pushing commit directly
|
@yashisrani please solve the previous reviews and incorporate the stuffs discussed in previous meet |
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
|
/lgtm |
|
The markdown lint introduce a burden for us. I saw too many failures about it |
Hmm i can also see the recent prs with failing lint, might be they are not aware of how to solve this, this lint error can easily solved by running "make format", we can update contributing docs to add this section |
|
@yashisrani you dont have to manually solve the markdown lint errors, this can be solved by running "make format" |
|
@LiZhenCheng9527 @yp969803 Sorry, sir, I was manually solving build issues... I was also frustrated. Thanks for helping me. bro, but it showing errors in other markdown file, not mine .. 
|
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
hzxuzhonghu
left a comment
There was a problem hiding this comment.
LGTM. Should add youtr preference in this doc
Signed-off-by: Yash Israni <yashisrani52@gmail.com>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: hzxuzhonghu The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
defer to @LiZhenCheng9527 to have a last look |
|
/lgtm |
What type of PR is this?
/kind documentation
Proposal for #1412
What this PR does / why we need it:
Which issue(s) this PR fixes:
Fixes : NONE