You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@fluss.apache.org by "Prajwal-banakar (via GitHub)" <gi...@apache.org> on 2026/02/06 09:14:09 UTC

[PR] [docs]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Prajwal-banakar opened a new pull request, #2588:
URL: https://github.com/apache/fluss/pull/2588

   <!--
   *Thank you very much for contributing to Fluss - we are happy that you want to help us improve Fluss. To help the community review your contribution in the best possible way, please go through the checklist below, which will get the contribution into a shape in which it can be best reviewed.*
   
   ## Contribution Checklist
   
     - Make sure that the pull request corresponds to a [GitHub issue](https://github.com/apache/fluss/issues). Exceptions are made for typos in JavaDoc or documentation files, which need no issue.
   
     - Name the pull request in the format "[component] Title of the pull request", where *[component]* should be replaced by the name of the component being changed. Typically, this corresponds to the component label assigned to the issue (e.g., [kv], [log], [client], [flink]). Skip *[component]* if you are unsure about which is the best component.
   
     - Fill out the template below to describe the changes contributed by the pull request. That will give reviewers the context they need to do the review.
   
     - Make sure that the change passes the automated tests, i.e., `mvn clean verify` passes.
   
     - Each pull request should address only one issue, not mix up code from multiple issues.
   
   
   **(The sections below can be removed for hotfixes or typos)**
   -->
   
   ### Purpose
   
   <!-- Linking this pull request to the issue -->
   Linked issue: close #2586 
   
   <!-- What is the purpose of the change -->
   The purpose of this change is to enhance the ConfigOptionsDocGenerator to produce cleaner, more professional MDX documentation. It fixes several formatting artifacts in the auto-generated configuration files, such as Table to list, incorrect type rendering and unformatted description placeholders, and improves the overall code quality of the generator itself.
   ### Brief change log
   
   <!-- Please describe the changes made in this pull request and explain how they address the issue -->
   Changed table to list format for better readability
   
   Enhanced Type Formatting: Refined the getType() logic to strip trailing generic brackets (e.g., converting String> to String) and normalized common Java types for documentation.
   
   Improved Descriptions: Updated cleanDescription() to replace %s placeholders with true to ensure generated sentences are grammatically complete and readable.
   
   Refined Scoping: Improved the logic for the "Scope" field to correctly categorize configurations as Client, Table, or Server based on their key prefixes.
   
   Code Quality & Checkstyle: * Fixed "ignored return value" warnings for File.mkdirs().
   
   Optimized imports and resolved reflective access warnings for the Internal annotation.
   
   Decoupled the generator from ConfigDocUtils to ensure it can run as a standalone utility without classpath resolution issues.
   
   ### Tests
   
   <!-- List UT and IT cases to verify this change -->
   Manually verified by running the ConfigOptionsDocGenerator main method and inspecting the resulting _partial_config.mdx file.
   
   Verified that the generated MDX renders correctly in a Markdown previewer with working anchors and valid formatting.
   
   Ran ./mvnw compile -pl fluss-docgen -am it passed perfectly
   
   <img width="1920" height="1080" alt="Screenshot 2026-02-06 142046" src="https://github.com/user-attachments/assets/e80054a1-f99e-41b8-942a-0aa927308d22" />
   
   
   ### API and Format
   
   <!-- Does this change affect API or storage format -->
   This change does not affect the Fluss runtime API or storage format. It only affects the internal documentation generation tool and the resulting .mdx files.
   
   ### Documentation
   
   <!-- Does this change introduce a new feature -->
   This PR improves the quality of the existing configuration documentation. No new user-facing features were added.


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docgen]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "Prajwal-banakar (via GitHub)" <gi...@apache.org>.
Prajwal-banakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-4109398989

   Hi @wuchong , the PR is ready for review. One thing to flag  issue #2912 was raised about `_partial_config.mdx` being regenerated on every full local project build since the exec plugin is bound to the `compile` phase, making it noisy in git status. Would it be better to change the phase binding to `none` so it only runs when explicitly called via
    `./mvnw compile -pl fluss-docgen -am`? Happy to address any review comments!


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docs]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "Prajwal-banakar (via GitHub)" <gi...@apache.org>.
Prajwal-banakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-3859294050

   Hi @wuchong,
   
   I've addressed your feedback from the previous PR ( #2474 ) and continued the work here to fulfill the requirements mentioned in your https://github.com/apache/fluss/pull/2474#issuecomment-3796875436. I haven't removed the manual tables yet as I'm waiting for your feedback on the automated generation first!


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docgen]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "Prajwal-banakar (via GitHub)" <gi...@apache.org>.
Prajwal-banakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-4297226402

   Hi jark, The current CI failure is due to _partial_config.mdx being auto-generated and now ignored after the recent change in PR #3146 i think the CI need to be update or do you have any other solutions for this? 


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docs]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "Prajwal-banakar (via GitHub)" <gi...@apache.org>.
Prajwal-banakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-3877794386

   Hi Jark! Totally understand, Congratulations to the team on reaching this milestone! good luck with the 0.9 RC1 release.


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docgen]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "polyzos (via GitHub)" <gi...@apache.org>.
polyzos commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-6251763577

   @pbanakar  whats the status here? should we close this or is it WIP?


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docgen]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "pbanakar (via GitHub)" <gi...@apache.org>.
pbanakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-6251887191

   Thanks for looking at this  @polyzos , this PR becames outdated because lack of review, i think we need to close this, and happy to open a fresh PR if this is Prefered to the community


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docgen]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "Prajwal-banakar (via GitHub)" <gi...@apache.org>.
Prajwal-banakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-4102286680

   Hi Jark, Would you have a moment to take a look when you get a chance? Happy to address any review comments.


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docs]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "wuchong (via GitHub)" <gi...@apache.org>.
wuchong commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-3877370742

   Thank you @Prajwal-banakar , I will continue to review this after 0.9 RC1 is out. Busy preparing the release. 


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [docgen]Refine ConfigOptionsDocGenerator and fix MDX formatting [fluss]

Posted by "pbanakar (via GitHub)" <gi...@apache.org>.
pbanakar commented on PR #2588:
URL: https://github.com/apache/fluss/pull/2588#issuecomment-5415506694

   Hi @wuchong This was our old PR and I think that this is also a important, I've followed your all instructions  https://github.com/apache/fluss/pull/2474#pullrequestreview-3750723431 in this PR, it works fine, but now the _partial_config.mdx the auto-generated file is now ignored after the recent change in PR #3146 so the ci is failing because of it so I think we need to call docgen builder in ci  and also configoptions.java is is changed significantly resolving merg conflicts is very Hard now, so if the release window still have a time I'll open a fresh PR quickly, PTAL And LMK!


-- 
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: issues-unsubscribe@fluss.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org