add(doc): Added workflow guide#234
Conversation
Signed-off-by: GitHub Action <action@github.com>
✅ Deploy Preview for kmesh-net ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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 guide to the project's automated documentation workflows. The new guide details the mechanisms for syncing CLI documentation, managing Docusaurus versions with internationalization considerations, and performing grammar checks on Chinese content. This update aims to provide clear instructions for contributors and maintainers, ensuring a consistent and high-quality documentation experience.
Highlights
- New Workflow Guide: A new documentation page has been added to outline the project's automated workflows, enhancing documentation quality and streamlining versioning processes.
- kmeshctl Sync Workflow Documented: The process for automatically syncing CLI documentation from the kmesh repository to the kmesh-website repository via a Pull Request is now documented, including triggers, steps, and maintenance notes.
- Docusaurus Versioning and i18n Handling Documented: The documentation clarifies the Docusaurus versioning process, specifically addressing how Chinese (i18n) documentation is handled. It details the implementation of a custom 404 page to guide users to English documentation when a Chinese version is unavailable for a new release.
- Chinese Grammar Check Workflow Documented: The documentation for the Chinese grammar checker workflow has been updated to specify that it now only scans files within the
docs/cn/zh/directory, ensuring focused and relevant feedback.
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 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. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
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
This PR adds a valuable workflow guide to the project's documentation. The guide is well-structured and clearly explains the automated workflows. I've provided a few suggestions to enhance consistency and readability, mainly by wrapping technical terms in backticks. Overall, this is a great contribution.
|
|
||
| ## 1. kmeshctl Sync Workflow | ||
|
|
||
| **Purpose:** Automatically sync the kmeshctl CLI documentation from the kmesh repository to the kmesh-website repository via a Pull Request (PR). |
There was a problem hiding this comment.
To maintain consistency with other parts of the document (like line 24), it's better to use the full repository name kmesh-net/website. Also, wrapping it in backticks improves readability.
| **Purpose:** Automatically sync the kmeshctl CLI documentation from the kmesh repository to the kmesh-website repository via a Pull Request (PR). | |
| **Purpose:** Automatically sync the kmeshctl CLI documentation from the kmesh repository to the `kmesh-net/website` repository via a Pull Request (PR). |
| ### Steps | ||
|
|
||
| 1. **Checkout Repositories:** The workflow checks out both the kmesh-website and kmesh repositories. | ||
| 2. **Sync with rsync:** Uses the rsync command to synchronize the `docs/ctl/` directory from kmesh into the docs/kmeshctl/ directory of kmesh-website. The --delete flag ensures that deleted files are also removed. |
There was a problem hiding this comment.
For consistency and improved readability, it's best to wrap commands (rsync), flags (--delete), and directory paths (docs/kmeshctl/) in backticks.
| 2. **Sync with rsync:** Uses the rsync command to synchronize the `docs/ctl/` directory from kmesh into the docs/kmeshctl/ directory of kmesh-website. The --delete flag ensures that deleted files are also removed. | |
| 2. **Sync with rsync:** Uses the `rsync` command to synchronize the `docs/ctl/` directory from kmesh into the `docs/kmeshctl/` directory of kmesh-website. The `--delete` flag ensures that deleted files are also removed. |
|
|
||
| 1. **Checkout Repositories:** The workflow checks out both the kmesh-website and kmesh repositories. | ||
| 2. **Sync with rsync:** Uses the rsync command to synchronize the `docs/ctl/` directory from kmesh into the docs/kmeshctl/ directory of kmesh-website. The --delete flag ensures that deleted files are also removed. | ||
| 3. **Create Pull Request:** If changes are detected, the workflow commits them and uses the `peter-evans/create-pull-request` action to create a PR in the kmesh-website repository. The branch name includes a timestamp to ensure uniqueness and prevent conflicts. |
There was a problem hiding this comment.
For consistency, please use the full repository name kmesh-net/website and wrap it in backticks. This aligns with the name used in the "Maintenance Notes" section.
| 3. **Create Pull Request:** If changes are detected, the workflow commits them and uses the `peter-evans/create-pull-request` action to create a PR in the kmesh-website repository. The branch name includes a timestamp to ensure uniqueness and prevent conflicts. | |
| 3. **Create Pull Request:** If changes are detected, the workflow commits them and uses the `peter-evans/create-pull-request` action to create a PR in the `kmesh-net/website` repository. The branch name includes a timestamp to ensure uniqueness and prevent conflicts. |
|
|
||
| ### Maintenance Notes | ||
|
|
||
| - **Secrets:** The `WEBSITE_PAT` secret must have write access to both the `kmesh-net/kmesh` and kmesh-net/website repositories. |
There was a problem hiding this comment.
For consistency, repository names should be wrapped in backticks to distinguish them from regular text.
| - **Secrets:** The `WEBSITE_PAT` secret must have write access to both the `kmesh-net/kmesh` and kmesh-net/website repositories. | |
| - **Secrets:** The `WEBSITE_PAT` secret must have write access to both the `kmesh-net/kmesh` and `kmesh-net/website` repositories. |
|
|
||
| ## 2. Docusaurus Versioning and i18n (Chinese) Handling | ||
|
|
||
| The Docusaurus versioning system is designed to create new versions based on the content of the source docs/ directory. When the docusaurus docs:version command is executed, it automatically generates a new versioned folder (e.g., `versioned_docs/version-X.Y.Z/`) containing all the English documentation. |
There was a problem hiding this comment.
For consistency and improved readability, it's best to wrap directory paths (docs/) and commands (docusaurus docs:version) in backticks.
| The Docusaurus versioning system is designed to create new versions based on the content of the source docs/ directory. When the docusaurus docs:version command is executed, it automatically generates a new versioned folder (e.g., `versioned_docs/version-X.Y.Z/`) containing all the English documentation. | |
| The Docusaurus versioning system is designed to create new versions based on the content of the source `docs/` directory. When the `docusaurus docs:version` command is executed, it automatically generates a new versioned folder (e.g., `versioned_docs/version-X.Y.Z/`) containing all the English documentation. |
|
|
||
| ### Chinese Documentation (i18n) Versioning | ||
|
|
||
| - The Docusaurus versioning command does not automatically create a corresponding versioned folder for the Chinese translations located in `i18n/zh/docusaurus-plugin-content-docs/.` |
There was a problem hiding this comment.
The trailing period . inside the backticks appears to be a typo. It should be placed outside the backticks to correctly represent the directory path.
| - The Docusaurus versioning command does not automatically create a corresponding versioned folder for the Chinese translations located in `i18n/zh/docusaurus-plugin-content-docs/.` | |
| - The Docusaurus versioning command does not automatically create a corresponding versioned folder for the Chinese translations located in `i18n/zh/docusaurus-plugin-content-docs/`. |
| - **Install Dependencies:** Installs the language-tool-python package. | ||
| - **Run Grammar Check:** Uses the LanguageTool library to scan only the .md files within the `docs/cn/zh/` directory and its subdirectories for Chinese (zh-CN) content. |
There was a problem hiding this comment.
For consistency and improved readability, it's best to wrap package names (language-tool-python), library names (LanguageTool), file extensions (.md), and language codes (zh-CN) in backticks.
| - **Install Dependencies:** Installs the language-tool-python package. | |
| - **Run Grammar Check:** Uses the LanguageTool library to scan only the .md files within the `docs/cn/zh/` directory and its subdirectories for Chinese (zh-CN) content. | |
| - **Install Dependencies:** Installs the `language-tool-python` package. | |
| - **Run Grammar Check:** Uses the `LanguageTool` library to scan only the `.md` files within the `docs/cn/zh/` directory and its subdirectories for Chinese (`zh-CN`) content. |
Signed-off-by: GitHub Action <action@github.com>
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: LiZhenCheng9527 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 |
This PR addresses the issue in kmesh-net/kmesh#1412
This PR updates the project's documentation to accurately reflect the implementation and behavior of our automated workflows.
Changes Include:
docs/cn/zh/directory, ensuring focused and relevant feedback.