[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17243503#comment-17243503
]
John Roesler commented on KAFKA-2967:
-------------------------------------
Hi [~JimGalasyn] ,
Thanks for that information!
It's very cool that you were able to convert the site to markdown. Thanks for
actually proving that it can be done with a reasonable level of effort.
I didn't understand the rationale for using ReadTheDocs. The docs are currently
hosted as a static site by the ASF for free. If we have markdown, we should be
able to use Jekyll or Hugo or something to render the markdown into HTML as
part of the job that currently copies the site over to the static host, right?
It seems like the ASF has some suggestions for how we could do this:
https://infra.apache.org/project-site.html
Thanks again,
-John
> 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)
