[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16364644#comment-16364644 ]
Ewen Cheslack-Postava commented on KAFKA-2967: ---------------------------------------------- Hey folks, I just want to point out that it isn't really useful to just upvote a particular format without more details. The point of restarting the discussion here was to be able to make progress on this with: # A practical choice of documentation system (guess I was correct that it would inevitably be a bikeshedding discussion) # A practical plan for a how this will work, including addressing concerns like Jay's about making it a clean integration with the rest of the website which likely would not make sense to translate into the docs system. # People who are a) ready to spend time on this and b) familiar enough with a particular tool that we have a reasonable plan It seems like everyone is only addressing 1. For all the asciidoc voters, can you outline details for 2 & 3? For RST/sphinx we already have a PR prepared (and in very short order, I might add) that is like 95% there. I need to find a bit of time to look into integrating it with the gradle build, but since we already knew rst inside out, we were able to do this very quickly. I have never used asciidoc and we won't have the time or resources to spend converting to that – can someone else contribute the resources for that? If not, are we actually concerned about it being in rst rather than asciidoc or are these just preferences, i.e. in what ways would asciidoc be such a huge win over rst? Note that a major reason we're still writing all our docs in html over 2 years later is bikeshedding on the particular format. > 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 > > 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 (v7.6.3#76005)