Hey Ewen, For "its own page" which location are you specifically thinking about?
Guozhang On Wed, Mar 9, 2016 at 6:48 AM, Grant Henke <ghe...@cloudera.com> wrote: > 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 > -- -- Guozhang
