fix(internal/gengapic): add API Versions section in pkg docs

[noahdietz]

Add package-level documentation section API Versions with brief explanation of interface-based versions, and list of client-interface-version tuples present in the package (or single sentence if all versions are the same).

Adds several tests, both golden file and unit, for new API versions section.

Adds a convenience helper apiVersion for extracting the google.api.api_version option. Adds a test convenience helper for setting google.api.api_version on ServiceOptions.

Fixes internal bug http://b/467066332.

[shollyman]

Consider this comment mostly bikeshedding, but we don't have to necessarily pick the colors today. The PR is fine for now, but I'm just looking towards the future a bit.

Do we have a more precise term than "API versions" for the section header? Service Interface Versions or something maybe?

Should we have a central page that explains how IBV works, and direct users there for more information? What header is used, etc? Or are services that use IBV going to have tooling to describe their IBV changelog in detail and that's where we're trying to link things down the line?

Do we expect a producer to have a mix of versioned and unversioned RPC services? If so, we may want to list all the services and note which services are unversioned. If there's no versioned services the current logic to elide this section seems reasonable.

[noahdietz]

Do we have a more precise term than "API versions" for the section header? Service Interface Versions or something maybe?

There will be some more public collateral here - AIP-9 will have new definitions that make this heading more reasonable. "API Interface Versions" would be the most precise term for this section (yes I know "application programming interface interface" is redundant 😄 ), but colloquially documentation will refer to these things as "API versions".

Should we have a central page that explains how IBV works

We will indeed be exporting a new AIP-185 section that we could link to as the central description for what it is and how it works. TBD on how we will be able to link to product-specific documentation if at all, but that would be best as it is the most relevant information on a per-client basis.

Do we expect a producer to have a mix of versioned and unversioned RPC services?...If there's no versioned services the current logic to elide this section seems reasonable.

We do not expect such a case. Agreed that if we do encounter that, we may want to include unversioned interfaces!