[
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:33 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|http://example.com] .
> 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)
