[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17244101#comment-17244101 ]
James Galasyn edited comment on KAFKA-2967 at 12/4/20, 4:30 PM: ---------------------------------------------------------------- [~tombentley], this is a good point – I think it can be mitigated by the extensions/plugins ecosystem. On the [ksqlDB docs site|https://docs.ksqldb.io/en/latest/], we've been able to achieve our design goals with markdown and a relatively small number of extensions ([requirements.txt| [https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]]). was (Author: jimgalasyn): [~tombentley], this is a good point – I think it can be mitigated by the extensions/plugins ecosystem. On the [ksqlDB docs site|https://docs.ksqldb.io/en/latest/], we've been able to achieve our design goals with markdown and a relatively small number of extensions ([requirements.txt|[https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]).] > 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 > Labels: documentation > > 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 (v8.3.4#803005)