[
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)
