kafka-jira mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ewen Cheslack-Postava (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (KAFKA-2967) Move Kafka documentation to ReStructuredText
Date Wed, 14 Feb 2018 19:19:00 GMT

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

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

Hey folks, I just want to point out that it isn't really useful to just upvote a particular
format without more details. The point of restarting the discussion here was to be able to
make progress on this with:
 # A practical choice of documentation system (guess I was correct that it would inevitably
be a bikeshedding discussion)
 # A practical plan for a how this will work, including addressing concerns like Jay's about
making it a clean integration with the rest of the website which likely would not make sense
to translate into the docs system. 
 # People who are a) ready to spend time on this and b) familiar enough with a particular
tool that we have a reasonable plan

It seems like everyone is only addressing 1. For all the asciidoc voters, can you outline
details for 2 & 3? For RST/sphinx we already have a PR prepared (and in very short order,
I might add) that is like 95% there. I need to find a bit of time to look into integrating
it with the gradle build, but since we already knew rst inside out, we were able to do this
very quickly. I have never used asciidoc and we won't have the time or resources to spend
converting to that – can someone else contribute the resources for that? If not, are we
actually concerned about it being in rst rather than asciidoc or are these just preferences,
i.e. in what ways would asciidoc be such a huge win over rst?

Note that a major reason we're still writing all our docs in html over 2 years later is bikeshedding
on the particular format.

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

Mime
View raw message