Ewen, I am okay with that. I agree something is better than nothing. I can touch up the patch today and open some jiras to track future work.
Thanks, Grant On Wed, Mar 9, 2016 at 1:50 AM, Ewen Cheslack-Postava <e...@confluent.io> wrote: > Agreed w/ Jay's comment on the PR that this is a great idea. What if we > included this as is, but instead of putting it all on the docs page we put > it on its own page? This: > > 1. Gets us something useful wrt protocol docs immediately. As you point > out, this is already useful to a bunch of people. > 2. Doesn't block on us figuring out a better way of managing docs (although > this may need adjustment once we choose a different format for docs). > 3. Gets the code checked in so any requests for refinements around protocol > docs can often be resolved with a patch to the code for autogenerating > them. > > -Ewen > > On Wed, Feb 24, 2016 at 11:57 PM, Grant Henke <ghe...@cloudera.com> wrote: > > > We have gotten a lot of requests for updating the protocol documentation: > > > > - KAFKA-3124: Update protocol wiki page to reflect latest > > request/response formats > > - KAFKA-2865: Improve Request API Error Code Documentation > > - KAFKA-3099: Please update A+Guide+To+The+Kafka+Protocol Wiki > > - KAFKA-2495: Protocol guide only partially updated after > > ConsumerMetadata* addition? > > - KAFKA-2494: Document ReplicaId in OffsetRequest in the protocol > guide > > > > Generating some docs to go either in the wiki or on the actual > > documentation site would definitely be valuable and ensure our protocol > > docs are up to date. Although the output could be fairly large, so I am > not > > sure it should go on the main page of our "one page" documentation site, > as > > the page is already fairly long to scroll. > > > > I made a very rough, super hacky, implementation that outputs some useful > > data in a similar format to the existing wiki. There is a pull request > and > > a gist of the output for anyone that it could help in the mean time > (links > > below). In the patch I listed some "todo" comments for things I would > > still like to see in the output. I don't have time to polish up the patch > > to completion now, due to other priorities. > > > > Is anyone interested in finishing the patch? If so please feel free to > use > > or ignore the code shared. > > > > - Pull request: https://github.com/apache/kafka/pull/970 > > - Gist of output: > > > > > https://gist.github.com/granthenke/dae9e60b5e548acead58#file-kafka_protocol-html > > - In browser preview of Gist: > > > > > https://rawgit.com/granthenke/dae9e60b5e548acead58/raw/a2da4279d6fd11e8056927695c7c091e58607f38/kafka_protocol.html > > > > Thanks, > > Grant > > -- > > Grant Henke > > Software Engineer | Cloudera > > gr...@cloudera.com | twitter.com/gchenke | linkedin.com/in/granthenke > > > > > > -- > Thanks, > Ewen > -- Grant Henke Software Engineer | Cloudera gr...@cloudera.com | twitter.com/gchenke | linkedin.com/in/granthenke
