[
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 11/30/20, 10:31 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 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.
Because it's time-consuming and error-prone to maintain the Kafka content both
in the AK site and in the CP docs site, we would remove the duplicative content
from the CP docs site, leaving only the CP-related content there, with links
(and redirects) back to the AK docs.
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?
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.
Because it's time-consuming and error-prone to maintain the Kafka content both
in the AK site and in the CP docs site, we would remove the duplicative content
from the CP docs site, leaving only the CP-related content there, with links
(and redirects) back to the AK docs.
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
>
> 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)
