search

ept / avrodoc

Documentation tool for Avro schemas
Apache License 2.0
148 stars 82 forks source link

Feature Request: Add types index page #11

Open mphuff opened 11 years ago

mphuff commented 11 years ago

Currently, there is a protocols index page that is displayed by default when you open an avrodoc file. It would be great to have a similar page specific to types. This way we could get a quick overview of all of the types, descriptions of the type, and a clickable link to each type.

ept commented 11 years ago

@mphuff Rather than a separate index page, would it make sense to include a list of types on the protocols on the same index page as the protocols index? Then in the case where you have no protocols, #13 is implicitly solved, and #12 wouldn't be needed (simplying the UI).

mphuff commented 11 years ago

@ept -- I don't think you will ever have NO protocols. In order to generate an AvroDoc file, you have to specify at minimum a single protocol definition file (which may only contain types but regardless is treated as a protocol).

Our particular use case is that we will be generating two different versions of avrodocs from the same project -- one that is JUST data types (customer consumption) and one that is data types + all Avro RPC messages (internal consumption). For the one that we will be shipping to customers, we would like them to be able to see a front page with all of the types by default. We are actually adding a custom piece of HTML after avrodocs have been generated that is a visualization of our types to make it easy for customers to see how our top-level data types are related. We would like for customers to be able to get back to this page once they've navigated around to various data types (hence #12 and #11).

Given the above scenario, #13 arose as a wishlist item -- being able to default to the types page. There will be a list of protocols but customers really don't care about those as they really have no true meaning. All they are interested in is the structure of the data that we'll be returning back to them.

Do these scenarios make sense / seem reasonable? At a minimum, if you decide that you'd like to just have the types on the protocols page, we need to be able to navigate back to that page (without having to click the browser back button). Right now the only way to get back to it is to strip off the anchor tag in the URL or click the browser back button until you're there.