dnskr opened a new issue, #7434: URL: https://github.com/apache/kyuubi/issues/7434
### Code of Conduct - [x] I agree to follow this project's [Code of Conduct](https://www.apache.org/foundation/policies/conduct) ### Search before asking - [x] I have searched in the [issues](https://github.com/apache/kyuubi/issues?q=is%3Aissue) and found no similar issues. ### What type of changes will we make to the documentation? Refactoring ### Affects Version(s) master/1.11 ### Improving the documentation ### **Description** Currently, the Apache Kyuubi documentation uses a hybrid approach, mixing **reStructuredText (.rst)** and **Markdown (.md)** files, while being processed by **Sphinx**. While this hybrid approach provides flexibility (using `myst-parser` for Markdown), it introduces several challenges: 1. Contributors need to be familiar with both syntaxes. 2. Cross-referencing between RST and MD files can be error-prone and hard to detect. 3. The build pipeline relies on multiple Sphinx extensions (like `myst-parser`, `sphinx-markdown-tables`) to bridge the gap. 4. Formatting features available in RST might not be easily replicable in Markdown (or vice-versa). **I propose migrating to a single technology to streamline the contribution process and improve documentation quality.** --- ### **Technology Comparison** Below is an analysis of the two primary paths for consolidation: #### **Option 1: Migrate to Markdown (using MyST-Parser)** * **Pros:** * Markdown is the de facto standard for most developers, so it is easier for new contributors. * Better preview support in GitHub, IDEs, and other tools. * MyST (Markedly Structured Text) provides almost all the power of RST (directives, roles) while remaining valid Markdown. * **Cons:** * Once we start using advanced features, the Markdown "cleanliness" can get cluttered with curly braces and colons. * Some advanced Sphinx features or specialized extensions may still favor RST's native structure. #### **Option 2: Migrate to reStructuredText (RST)** * **Pros:** * RST is the native format for Sphinx, offering the most robust support for technical documentation features. * Eliminates the need for "bridge" plugins like `myst-parser`. * **Cons:** * RST syntax is more verbose and less intuitive for casual contributors compared to Markdown. * Limited rendering outside of Sphinx-based environments. --- ### **Action Plan** 1. Decide on the target format (Markdown/MyST vs. RST). 2. Convert a few effortless directories to the target format using automated tools or AI agents to verify the approach. 3. Deprecate a non-target format in contributing guidelines. 4. Convert other pages, including those requiring fixing broken cross-references and formatting edge cases. 5. Remove unnecessary Sphinx dependencies from `docs/requirements.txt` and configuration from `conf.py` after migration. --- **What do you think?** Should we standardize on Markdown for ease of contribution or stick with RST for its native power? ### Are you willing to submit PR? - [x] Yes. I would be willing to submit a PR with guidance from the Kyuubi community to improve. - [ ] No. I cannot submit a PR at this time. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
