[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17244159#comment-17244159 ] James Galasyn edited comment on KAFKA-2967 at 12/4/20, 5:37 PM: [~tombentley] I'm not sure that we could generate links, but it seems at least plausible that we could. :D There's also the possibility of applying arbitrary CSS to the built pages, which mkdocs allows. We do a bit of that on the ksqlDB site in [extra.css|https://github.com/confluentinc/ksql/blob/master/docs/stylesheets/extra.css]. was (Author: jimgalasyn): [~tombentley] I'm not sure that could generate links, but it seems at least plausible that we could. :D There's also the possibility of applying arbitrary CSS to the built pages, which mkdocs allows. We do a bit of that on the ksqlDB site in [extra.css|https://github.com/confluentinc/ksql/blob/master/docs/stylesheets/extra.css]. > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17244101#comment-17244101 ] James Galasyn edited comment on KAFKA-2967 at 12/4/20, 4:32 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|http://example.com] . 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|[https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]] . > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17244101#comment-17244101 ] James Galasyn edited comment on KAFKA-2967 at 12/4/20, 4:31 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| [https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]] . > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17244101#comment-17244101 ] James Galasyn edited comment on KAFKA-2967 at 12/4/20, 4:31 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|[https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]]). > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17244101#comment-17244101 ] James Galasyn edited comment on KAFKA-2967 at 12/4/20, 4:30 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|[https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]).] > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17244101#comment-17244101 ] James Galasyn edited comment on KAFKA-2967 at 12/4/20, 4:30 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| [https://github.com/confluentinc/ksql/blob/master/docs/requirements.txt]]). > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17241113#comment-17241113 ] James Galasyn edited comment on KAFKA-2967 at 11/30/20, 10:49 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. 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16357817#comment-16357817 ] Gwen Shapira edited comment on KAFKA-2967 at 2/9/18 1:45 AM: - Having used both, I have to say that I like Asciidoc's version of markdown is much easier to use. The available plugins (especially for Atom) are better too. [~vikgamov] is a Gradle expert (or at least an official reviewer of O'Reilly Gradle book), and given our Gradle/doc integration pains in the past, it is good to have a community volunteer with the necessary expertise to maintain the integration. How does everyone else feel on Asciidoc vs RST? (Sorry for bikeshedding, [~ewencp], but I think it is worthwhile to think a bit about a decision we'll have to live with for the coming years). was (Author: gwenshap): Having used both, I have to say that I like Asciidoc's version of markdown is much easier to use. The available plugins (especially for Atom) are better too. [~vikgamov] is a Gradle expert (or at least an official reviewer of O'Reilly Gradle book), and given our Gradle/doc integration pains in the past, it is good to have a community volunteer with the necessary expertise to maintain the integration. How does everyone else feel on Asciidoc vs RST? > 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 (v7.6.3#76005)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16357798#comment-16357798 ] Vik Gamov edited comment on KAFKA-2967 at 2/9/18 1:27 AM: -- Guys, Have we ever consider to use asciidoc [http://asciidoctor.org/docs/what-is-asciidoc/] for writing documentation rather rst or markdown? There are bunch of known projects who use asciidoc [http://asciidoctor.org/docs/what-is-asciidoc/#who-s-using-asciidoc] (like GIT documentation and Neo4j database docs, github supports it) It's very powerful and suitable for writing complex text (like books) Oreilly uses it for book writers, there are plugins for gradle to generate html5, pdf, and even mobile optimized formats like epub and mobi. It has wide range integrations (including gradle and maven) [http://asciidoctor.org/docs/#references-and-developer-resources] Here is how it different than markdown (for example) [http://asciidoctor.org/docs/user-manual/#compared-to-markdown]. Thank you was (Author: vikgamov): Guys, Have we ever consider to use asciidoc [http://asciidoctor.org/docs/what-is-asciidoc/] for writing documentation rather rst or markdown? It's very powerful and suitable for writing complex text (like books) Oreilly uses it for book writers, there are plugins for gradle to generate html5, pdf, and even mobile optimized formats like epub and mobi. It has wide range integrations (including gradle and maven) [http://asciidoctor.org/docs/#references-and-developer-resources] Here is how it different than markdown (for example) http://asciidoctor.org/docs/user-manual/#compared-to-markdown. Thank you > 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 (v7.6.3#76005)
