kafka-jira mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vik Gamov (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (KAFKA-2967) Move Kafka documentation to ReStructuredText
Date Fri, 09 Feb 2018 01:22:00 GMT

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

Mime
View raw message