wuchong commented on PR #2474: URL: https://github.com/apache/fluss/pull/2474#issuecomment-3796875436
Hi @Prajwal-banakar, The goal of generating HTML was primarily to make it easy to embed configuration content into our documentation Markdown files. However, after reviewing the Docusaurus documentation, I believe it’s actually simpler and more maintainable to embed **Markdown (or MDX) directly into Markdown files** using Docusaurus’ built-in MDX support—see: https://docusaurus.io/docs/3.8.1/markdown-features/react#importing-markdown Here’s a refined proposal: 1. **Generate configs as an MDX partial**: Output the auto-generated configuration reference into a file like `_partial_config.mdx` under `website/docs/_configs/`. This file can then be imported and rendered in any doc page using MDX. 2. **Support logical grouping via annotations**: Introduce a `@Documentation.Section` annotation in the source code (e.g., on config fields or classes). Use the provided section name to generate corresponding headers in the output. Preserve the existing section structure from the current config doc at https://fluss.apache.org/docs/next/maintenance/configuration/ as the baseline. 3. **Allow overriding system-dependent defaults**: Add a `@Documentation.OverrideDefault` annotation to let developers specify a documentation-friendly default value (e.g., for `client.scanner.io.tmpdir`, which defaults to a system property). This avoids exposing environment-specific values like `/tmp` in the docs. 4. **Format defaults as inline code**: Render all “Default” values in `<code>` style (e.g., `` `7d` ``) for better readability and consistency. 5. **Include a “Type” column**: Clearly indicate the type of each configuration option (e.g., `Duration`, `Boolean`, `MemorySize`, `String`) in the generated table. This approach keeps the docs accurate, maintainable, and aligned with Docusaurus best practices while enabling full automation of config documentation. -- 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]
