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

["Jorge Esteban Quilcate Otoya (Jira)" <ji...@apache.org>]

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

Jorge Esteban Quilcate Otoya commented on KAFKA-2967:
-----------------------------------------------------

Hi everyone. I'd love to see this migration happening to improve contributions and user-experience around Kafka documentation.

I took James's idea of using Pandoc a bit further and put it together with Hugo (similar to what Flink does), and migrated most of the documentation under `docs/` to Markdown: [https://github.com/jeqo/ak-docs]

Hopefully the readme is good enough for anyone who wants to test it. Did some initial integration with kafka-site to check how that would look.

There are some style minor details (e.g. URLs, image sizing, kafka streams navigation, generate JSON instead of HTML on Config/Metrics, etc) that could be discussed in a following issue, but I'd like to get feedback at this point to see if the migration seems promising and what the next steps could be.

> 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.20.10#820010)