Google-cloud-ruby: Google Cloud docs not showing BigQuery Guide

[blowmage]

Yesterday google-cloud 0.51.0 was released and added google-cloud-bigquery-data_transfer. The side navigation for the meta package links to BigQuery DataTransfer, but the result gives a 404. I think this may be because BigQuery DataTransfer is nested under BigQuery, and the angular app is not treating BigQuery DataTransfer as a separate package.

[quartzmo]

I'll build the docs today locally, and see what (if anything) can be done about this.

[quartzmo]

If you select master version in the left pulldown, then the link to BigQuery DataTransfer works! BUT the "guide" content at BigQuery is missing!

[tswast]

The PHP team is having similar problems at https://github.com/GoogleCloudPlatform/google-cloud-php/issues/826

[quartzmo]

@tswast Thanks, good to know.

[blowmage]

Good news, I got it to work. I had missed some files in my manual fix to the docs and adding all of them has fixed the nav.

[quartzmo]

I'm going to change "DataTransfer" to "Guide" in the title of this issue, since we still have that problem.

[quartzmo]

Remaining issue: The "guide" content at BigQuery is missing!

[quartzmo]

@blowmage The JSON resource files for google-cloud are the copied files of all its included packages. The problem is that since the files for Data Transfer contain google/cloud/bigquery.json (due to this module being present in Data Transfer), and Data Transfer follows BigQuery in the copying process, the bigquery.json containing the guide is now overwritten by the blank bigquery.json from Data Transfer.

The most obvious solution to me is to exclude ALL the blank module files from the jsondoc output. This will have side effects in that these file currently produce blank (but not 404) views in the site app. For example:

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

If these blank (no docs, no methods) modules are excluded from the output, the path above will be redirected with a Not Found message.

What do you think?

[blowmage]

Would building the docs for the meta package in a different order, with bigquery-data_transfer running _before_ bigquery, preserve the bigquery.json file we want to see?

[quartzmo]

@blowmage That's a definitely possibility that should solve this particular problem with no side effects that I can think of... (This module overlap may still produce some other problem after the reversal, but I can't think of it.)

I'll try it out locally.

[quartzmo]

It works, here's the patch:

--- a/Rakefile
+++ b/Rakefile
@@ -288,8 +288,8 @@ namespace :jsondoc do
     rm_rf gh_pages + "json/google-cloud/#{version}/google", verbose: true

     google_cloud_gems = [
-      "google-cloud-bigquery",
       "google-cloud-bigquery-data_transfer",
+      "google-cloud-bigquery",
       "google-cloud-core",
       "google-cloud-datastore",
       "google-cloud-debugger",
@@ -312,8 +312,7 @@ namespace :jsondoc do
     ]
     # Currently excluded: "gcloud", "google-cloud", "stackdriver", "stackdriver-core",
     #                     "google-cloud-spanner", "google-cloud-env"
-    gems.each do |gem|
-      next unless google_cloud_gems.include? gem
+    google_cloud_gems.each do |gem|

       ver = if version == "master"
               "master" # When building master, all content should be from master

[blowmage]

how about this instead:

(google_cloud_gems & gems).each do |gem|

We want the verification that gems gives us, but the order that google_cloud_gems gives us. Doing an intersection of the two arrays should maintain that.

[quartzmo]

Works, good idea.