Google-cloud-ruby: Display the content for GAPIC/GRPC API version such as 'V1' menu item

[swcloud]

Right now, if a user clicks 'V1' menu item on the left navigation panel, the right side displays an empty page. We should add content for this menu item or find a way to not change the content on the right side when the menu item is clicked, i.e., when a user clicks 'V1', what it only does is to expand the sub menu items.

[quartzmo]

Currently, when any left nav item is clicked, related content is shown in the main page. Clicking any of the top-level "service" nav items ('BigQuery', 'Datastore', etc) results in the display of an overview discussion of the service. Example:

https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/v0.23.0/google/cloud/datastore

Google Cloud Datastore is a fully managed, schemaless database for storing non-relational data. You should feel at home if you are familiar with relational databases, but there are some key differences to be aware of to make the most of using Datastore.

I think for consistency we should stick to this pattern. Clicking the 'V1' should display an overview discussion informing the user about purpose and expected usage of the GAPIC API.

[danoscarmike]

@omaray to flesh out design. At minimum we need to provide content / redirect.

[geigerj]

@landrito Let's put the README content in the version landing page in the meantime. That will fulfill the beta-blocking/P0 requirement.

[danoscarmike]

@landrito @geigerj can you please revisit? Is priority P0 appropriate here - critical issue / imminent release blocking? Thanks.

[landrito]

I think this can be resolved. @eoogbe made this https://github.com/googleapis/toolkit/pull/1358 which should address this. @geigerj @eoogbe can you confirm?

[geigerj]

@danoscarmike This is blocking for all new beta-level releases. I'm not clear on the distinction between P0 and P1 that we're using. As @landrito said, @eoogbe is actively working on this.

[danoscarmike]

@swcloud can you please verify and close this issue if resolved? Thanks!

[geigerj]

@danoscarmike this issue is not resolved; there is still WIP. It's not blocking _any_ imminent releases, but it is blocking _beta_ releases. I think P0 is probably still accurate.

[danoscarmike]

Understood. Thanks @geigerj

[geigerj]

@landrito temporarily assigning this to you, as this will be resolved by the global GAPIC refresh you are working on in api-client-staging currently. When the api-client-staging refresh is done, we'll need to create PRs to this repo and push the documentation updates. You can either do that or reassign to me to do so once the CI passes on api-client-staging.

[danoscarmike]

Ping. @landrito @geigerj can you please update the status of this one?

[geigerj]

I will regenerate monitoring today, and once that's pushed to the github.io site we can verify the fixes that we made in the generator.

[quartzmo]

In Video Intelligence, there is now content configured from the V1Beta2 module for the link/page of this name. However, it is not showing up. I think this may be due to a limitation in our gcloud-jsondoc tool, which I believe only generates documentation from classes, not modules. I'll look into this and confirm.

[geigerj]

@quartzmo Once you have a better idea of what the limitation is, could you give me a sense of the approximate cost of changing the tool to support module-level documentation? Also, whether there's some other approach we can take with the code generator to feed these docs to the gcloud-jsondoc tool -- can we write this to a text file and feed it through the the jsondoc Rake task?

[quartzmo]

could you give me a sense of the approximate cost of changing the tool...

I spent most of today working on it, but I did not yet find a solution. So I can only guess that it will take another day, or two.

whether there's some other approach we can take with the code generator to feed these docs to the gcloud-jsondoc tool

I have a feeling this might be easier. If I get any ideas I won't hesitate to run them by you here on this issue.

[geigerj]

Thanks, @quartzmo.

[quartzmo]

@geigerj Will it work with the generator to move these top-level docs to a declaration of the module that is in a doc directory? In the case of Video Intelligence V1Beta2, this would be from lib/google/cloud/video_intelligence/v1beta2.rb#L51-L62 to lib/google/cloud/video_intelligence/v1beta2/doc/google/cloud/videointelligence/v1beta2/video_intelligence.rb#L18.

[geigerj]

@quartzmo Sure, we can try that. (It's slightly complicated from the generator side because there is not always a module in the doc/ directory currently that corresponds to the API client module, e.g., for any API that doesn't have a cloud package in its proto namespace. But we can generate a new file in those cases.)

Before I start making the change to the generator, were you able to confirm that this will work when you make the change manually?

[quartzmo]

Yes, it works for me locally after changing the gcloud-jsondoc tool to include modules as well as classes.

FYI, the left nav item can be mapped to any jsondoc output. The problem is that the YARD objects used to generate these outputs do not correspond to files, and for some reason I could not find any documentation output from the V1beta2 module docs in the existing location outside of doc/, even though the file seemed to be in the path. (It is not excluded in .yardopts.) I can keep trying to debug it if it seems better to you than moving the docs.

[geigerj]

Thanks for looking into this, @quartzmo.

@eoogbe is going to make the change in the code generator. We expect to have an update early next week.

[quartzmo]

OK, I'll push the change to the gcloud-jsondoc tool to include modules as well as classes now.

[quartzmo]

@geigerj

I was just alerted by @blowmage to an issue in the page that was generated following #1714: On the Google::Cloud::VideoIntelligence::V1beta2 page, the two links in the table are broken.

I'm not sure of the root cause, but I noticed that the broken links have a repeated v1beta2 directory: ../v1beta2/v1beta2/..

Correct:

https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-video_intelligence/master/google/cloud/videointelligence/v1beta2/videointelligenceserviceclient

Broken:

https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-video_intelligence/latest/google/cloud/videointelligence/v1beta2/v1beta2/videointelligenceserviceclient

[geigerj]

@eoogbe This looks like an issue with the toolkit template that's generating these lines. Could you take a look?

[eoogbe]

@geigerj It looks like it's this line that's causing the problem. It's based on the brittle proto_path property which varies based on the common directory of all the src protos. The tests set the value explicitly which is probably why we didn't catch it. We need to either generate the url with a less brittle property or make the property itself easier to predict.

[geigerj]

@eoogbe Agreed. Suggest that instead of using proto_path from the PackageMetadata we should instead use the package declared for the .proto file that contains the service being documented. This should contain the version already, so there will be no need to append the version explicitly in RubyPackageMetadataTransformer.generateTocContent().

[eoogbe]

How do I access the file path from the ProtoFile object?

[geigerj]

@eoogbe For the package, you want protoFile.getProto().getPackage().

[geigerj]

From @blowmage on #1714:

K, FWIW I think those links will be problematic because they always go to the latest release. If you are looking at a previous release (or master) and click those links they will jump you to latest. That might be frustrating for users who aren't expecting it to change the version they are looking at.

@eoogbe we should also switch to use a relative link here to avoid the issue @blowmage raises.

[eoogbe]

What does a correct relative link look like? For example, if this is the absolute:
https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-video_intelligence/latest/google/cloud/videointelligence/v1beta2/videointelligenceserviceclient

[geigerj]

https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-video_intelligence/v1.0.0/google/cloud/videointelligence/v1 now shows a table of contents. Closing this issue.