[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16357798#comment-16357798
]
Vik Gamov commented on KAFKA-2967:
----------------------------------
Guys,
Have we ever consider to use asciidoc
[http://asciidoctor.org/docs/what-is-asciidoc/] for writing documentation
rather rst or markdown?
It's very powerful and suitable for writing complex text (like books)
Oreilly uses it for book writers, there are plugins for gradle to generate
html5, pdf, and even mobile optimized formats like epub and mobi.
It has wide range integrations (including gradle and maven)
[http://asciidoctor.org/docs/#references-and-developer-resources]
Here is how it different than markdown (for example)
http://asciidoctor.org/docs/user-manual/#compared-to-markdown.
Thank you
> 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)
