KAFKA-3361: Initial protocol documentation page and generation#970
KAFKA-3361: Initial protocol documentation page and generation#970granthenke wants to merge 2 commits into
Conversation
granthenke
commented
Feb 25, 2016
granthenke
commented
- Moves all generated docs under /docs/generated
- Generates docs for Protocol, Errors, and ApiKeys
- Adds new protocol.html page
granthenke
force-pushed
the
protocol-doc-wip
branch
from
8c3f730 to
254f7f8
Compare
|
This is a super cool idea. |
|
This is great. Where's the tool you used to generate this? Can it do markdown? Would love to work on converting the Kafka main-page docs to gitbook.com format https://www.gitbook.com |
|
@christian-posta No tool was used. All the code used to generate this is in this pull request. Just some hacked together code to build the output. |
- Moves all generated docs under /docs/generated - Generates docs for Protocol, Errors, and ApiKeys - Adds new protocol.html page
granthenke
force-pushed
the
protocol-doc-wip
branch
from
254f7f8 to
c366ab1
Compare
|
Below was my original WIP message:
I have updated the patch to be a "real" patch. The protocol docs still need some work. But that work is tracked by the umbrella jira here: KAFKA-3360. |
granthenke
changed the title
|
@ewencp Ping for review. Thoughts on how this should link into the main docs? |
|
I agree that this should be a separate page (until we break down our documentation). How about: Add a link to the side-bar (top.html) that will point to this page directly? |
| @@ -0,0 +1,163 @@ | |||
| <h3><a id="protocol" href="#protocol">Kafka Wire Protocol</a></h3> | |||
|
|
|||
| <p>This document covers the protocol implemented in Kafka 0.8 and beyond. It is meant to give a readable guide to the protocol that covers the available requests, their binary format, and the proper way to make use of them to implement a client. This document assumes you understand the basic design and terminology described <a href="https://kafka.apache.org/documentation.html#design">here</a></p> | |||
There was a problem hiding this comment.
Since this page is now in the version control and generated, I'm not sure this makes sense... we'll have a separate generated doc with each release, documenting the protocol for current version.
|
@gwenshap Good idea. The side-bar is probably the best place. I can send a PR to the site repo after this gets in. I updated the PR to remove the version. |
|
LGTM (both the code and the plan). Also, we want to publish the protocol for 0.9 too, right? So we'll want to cherrypick this to the 0.9 branch. |
|
Sorry, this doesn't cherrypick cleanly. |
4 participants
