[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText

["Vik Gamov (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16357798#comment-16357798 ] 

Vik Gamov edited comment on KAFKA-2967 at 2/9/18 1:27 AM:
----------------------------------------------------------

Guys,

Have we ever consider to use asciidoc [http://asciidoctor.org/docs/what-is-asciidoc/]  for writing documentation rather rst or markdown?

There are bunch of known projects who use asciidoc [http://asciidoctor.org/docs/what-is-asciidoc/#who-s-using-asciidoc] (like GIT documentation and Neo4j database docs, github supports it)

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


was (Author: vikgamov):
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)