[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15049329#comment-15049329
]
Gwen Shapira commented on KAFKA-2967:
-------------------------------------
RST is very commonly used in open source projects and is very well documented
and easy to google. I don't think it will be an impediment for contributions
(it isn't in Python, Sqoop, Flume, etc). I'm not sure flexibility of
formatting is an advantage in project documentation where standardization is
often better.
Regarding the output:
Sphinx supports HTML themes, so we are really very flexible regarding the
looks. We can use existing themes or make our own to better match the look of
the Kafka site. You can see how this works and few examples here:
http://sphinx-doc.org/theming.html
Here are some documentation sites built with Sphinx and RST, so you can see
some of the options:
http://docs.confluent.io/2.0.0/platform.html
http://sqoop.apache.org/docs/1.4.6/SqoopUserGuide.html
https://flume.apache.org/
The main point is that they all look different, and we can make sure the Kafka
documentation will work for us.
By separating our content from the look and feel, we really do make it easier
for people to contribute documentation. Just moving the docs to our github made
a huge uptick in contributions. Automating doc generation was another step
toward improving documentation (and made life easier for release managers).
I'm trying for another incremental improvement here :)
> 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
>
> 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)
