[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15183815#comment-15183815
]
Christian Posta commented on KAFKA-2967:
----------------------------------------
All,
I've got a quick spike of converting docs to gitbook https://www.gitbook.com
which is basically markdown with some styling and can build websites, ebooks,
pdf, etc.
Point of this spike was to 1) get some feedback 2) understand how the current
docs are folded into the website, and 3) figure out where some of the configs
(e.g., broker configs) are in the website at apache, but not in the src :) For
example, not all of these in the table here
http://kafka.apache.org/documentation.html#brokerconfigs are in here
https://github.com/apache/kafka/blob/trunk/docs/configuration.html#L147
This branch here as all of the code/integrated with gradle builds, etc
https://github.com/christian-posta/kafka/tree/ceposta-doco
again, this is currently WIP for discussion purposes, not complete by any means.
> 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
>
> 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
(v6.3.4#6332)
