[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17241113#comment-17241113
]
James Galasyn edited comment on KAFKA-2967 at 12/3/20, 6:53 PM:
----------------------------------------------------------------
Since I inherited the Streams docs, I've come to appreciate the points made by
[~gwenshap] and [~ewencp]. I'm proposing a somewhat different solution: migrate
the HTML-based docs to markdown and host them on ReadTheDocs. We used this
approach successfully for the [ksqlDB docs|https://docs.ksqldb.io/en/latest/],
and there's no reason it won't work for the AK docs.
Last week, I took a couple of hours and manually converted the entire AK doc
set to markdown by using Pandoc: [ak-docs-proto
repo|https://github.com/confluentinc/ak-docs-proto]. There's some more work to
do, like fixing headings and updating links, but as a proof-of-concept, it
works okay.
Once the markdown is cleaned up, we would move it to the docs directory in the
public AK GitHub repo. There are numerous options for building and hosting, for
example, ksqlDB uses a ReadTheDocs project with a Basic account ($50/month).
The ksdqlDB docs have used this model successfully since November 2019, so the
execution risk is low.
I looked around at other ASF projects to see how they handle docs, and there's
no prescribed solution. Each has its own approach.
* *Pulsar*: [https://github.com/apache/pulsar/tree/master/site2] Markdown and
[https://docusaurus.io/]
* *Flink*: [https://github.com/apache/flink/tree/master/docs] Markdown and
Jekyll
* *Ant*: Raw HTML [https://github.com/apache/ant/tree/master/manual]
* *Calcite*: Markdown and Jekyll
[https://github.com/apache/calcite/tree/master/site/_docs]
* *Cassandra*: RestructuredText and Sphinx
[https://github.com/apache/cassandra/tree/trunk/doc]
* *Hadoop*:
[https://github.com/apache/hadoop/blob/trunk/hadoop-common-project/hadoop-auth/src/site/markdown/BuildingIt.md]
Also, we could use whatever hosting solution we use currently for
[https://kafka.apache.org/documentation/].
The big win for the community is getting the docs into markdown, which greatly
increases the ease of contribution and flexibility of presentation.
was (Author: jimgalasyn):
Since I inherited the Streams docs, I've come to appreciate the points made by
[~gwenshap] and [~ewencp]. I'm proposing a somewhat different solution: migrate
the HTML-based docs to markdown and host them on ReadTheDocs. We used this
approach successfully for the [ksqlDB docs|https://docs.ksqldb.io/en/latest/],
and there's no reason it won't work for the AK docs.
Last week, I took a couple of hours and manually converted the entire AK doc
set to markdown by using Pandoc: [ak-docs-proto
repo|https://github.com/confluentinc/ak-docs-proto]. There's some more work to
do, like fixing headings and updating links, but as a proof-of-concept, it
works okay.
Once the markdown is cleaned up, we would move it to the docs directory in the
public AK GitHub repo and set up a ReadTheDocs project with a Basic account
($50/month). RTD will build from our GH branches and host the site for us.
The ksdqlDB docs have used this model successfully since May 2020, so the
execution risk is low. [~mjsax], [~vvcephei], and [~mdrogalis], what do you
think?
> 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)
