[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16357817#comment-16357817
]
Gwen Shapira edited comment on KAFKA-2967 at 2/9/18 1:45 AM:
-------------------------------------------------------------
Having used both, I have to say that I like Asciidoc's version of markdown is
much easier to use. The available plugins (especially for Atom) are better too.
[~vikgamov] is a Gradle expert (or at least an official reviewer of O'Reilly
Gradle book), and given our Gradle/doc integration pains in the past, it is
good to have a community volunteer with the necessary expertise to maintain the
integration.
How does everyone else feel on Asciidoc vs RST?
(Sorry for bikeshedding, [~ewencp], but I think it is worthwhile to think a
bit about a decision we'll have to live with for the coming years).
was (Author: gwenshap):
Having used both, I have to say that I like Asciidoc's version of markdown is
much easier to use. The available plugins (especially for Atom) are better too.
[~vikgamov] is a Gradle expert (or at least an official reviewer of O'Reilly
Gradle book), and given our Gradle/doc integration pains in the past, it is
good to have a community volunteer with the necessary expertise to maintain the
integration.
How does everyone else feel on Asciidoc vs RST?
> 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)
