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

["Ewen Cheslack-Postava (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16354762#comment-16354762 ] 

Ewen Cheslack-Postava commented on KAFKA-2967:
----------------------------------------------

I'd like to raise this once again and see what people think of the current state. The docs have grown increasingly hacky, especially with the streams docs sort of ending up on their own page, weirdly integrated with the table of contents, javascript hacks to get things rendered properly client-side, and what I consider a mess of SSIs.

I'd like to propose a solution that I think addresses most of the concerns from the thread. I had some offline discussion with some other folks and we discussed a few different options, including markdown, which I assumed would be the most popular for people writing docs. We concluded that the support from just simple markdown wasn't going to be good enough and that usually you end up having to adopt some layer on top of it anyway (and have to learn all the details of that tool). Depending on what you choose, the ability to integrate with the rest of the site well has varying levels of difficulty.

 

I'd like to propose an alternative that Gwen mentioned originally – use sphinx/rst. 
 * Theming to both reuse existing styling and layout is trivial.
 * Its a full docs solution and has all the doodads and plugins we'd need as the docs continue to grow.
 * Migrate progressively, and only migrate docs for now. We'll just be compiling down to html anyway, so we can move progressively, and can choose which parts of the site we want to live under sphinx. Of course there is one caveat that the initial conversion will probably require a big chunk of work since the docs are currently just one giant page and we'd probably want it broken up from the get-go. But html content could still easily be used and linked to.
 * Can easily escape hatch back to raw html if we ever need it / want more flexibility in layout / etc. It's a trivial command to do so.
 * Maybe most importantly, I'm prepared to take on the work of setting up the build & doing initial conversion.

The main drawback is that not everyone will be familiar with rst. As I mentioned, this is actually a problem with even markdown as you usually need additional tooling on top of the raw syntax so I don't see it as a big problem. The other annoyance is that while we can include html snippets (e.g. configs and metrics autogenerated docs) directly, but it'll look a lot better if we actually convert the autogeneration to spit out rst instead. We don't have too many of these and it's just another method to generate the output, so probably best to just do that at the same time as initial conversion.

 

I think it is easy to bikeshed on something like this (everyone has their favorite tool), but does anybody have any objections to this proposal? I'd like to be able to move forward with this soon as I know dealing with the current form of docs has been a constant pain - there are fewer Connect docs than there should be (and would be if it wasn't so hard to add them) and Streams is constantly fighting with the html docs. If nobody pipes up in a few days, I'll plan to execute and we can take the rest of the discussion to a PR.

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