[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText

["James Galasyn (Jira)" <ji...@apache.org>]

    [ 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|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)