[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17693546#comment-17693546 ]
Jorge Esteban Quilcate Otoya commented on KAFKA-2967: ----------------------------------------------------- Hi everyone. I'd love to see this migration happening to improve contributions and user-experience around Kafka documentation. I took James's idea of using Pandoc a bit further and put it together with Hugo (similar to what Flink does), and migrated most of the documentation under `docs/` to Markdown: [https://github.com/jeqo/ak-docs] Hopefully the readme is good enough for anyone who wants to test it. Did some initial integration with kafka-site to check how that would look. There are some style minor details (e.g. URLs, image sizing, kafka streams navigation, generate JSON instead of HTML on Config/Metrics, etc) that could be discussed in a following issue, but I'd like to get feedback at this point to see if the migration seems promising and what the next steps could be. > Move Kafka documentation to ReStructuredText > -------------------------------------------- > > Key: KAFKA-2967 > URL: https://issues.apache.org/jira/browse/KAFKA-2967 > Project: Kafka > Issue Type: Bug > Reporter: Gwen Shapira > Assignee: Gwen Shapira > Priority: Major > Labels: documentation > > Storing documentation as HTML is kind of BS :) > * Formatting is a pain, and making it look good is even worse > * Its just HTML, can't generate PDFs > * Reading and editting is painful > * Validating changes is hard because our formatting relies on all kinds of > Apache Server features. > I suggest: > * Move to RST > * Generate HTML and PDF during build using Sphinx plugin for Gradle. > Lots of Apache projects are doing this. -- This message was sent by Atlassian Jira (v8.20.10#820010)