prototype: removing product_documentation_override with more values in librarian/sdk.yaml#16793
prototype: removing product_documentation_override with more values in librarian/sdk.yaml#16793jskeet wants to merge 2 commits intogoogleapis:mainfrom
Conversation
This is a version of librarian with googleapis/librarian#5573 applied. We should not merge this PR, but if we're happy with the changes we can do something similar after that PR is merged and we've updated to a version including it.
jskeet
added
the
do not merge
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request removes numerous product_documentation_override entries from librarian.yaml and corresponding metadata files. While this cleanup aims to simplify the configuration, it frequently results in the loss of deep links to specific product documentation, replacing them with generic landing pages. I have identified several instances where this loss of specificity negatively impacts the user experience and documentation quality. Please restore the specific documentation overrides for the BigQuery, Cloud DNS, BigQuery Reservations, and Apigee Connect libraries to ensure users are directed to the most relevant resources.
| name_pretty_override: Google Cloud BigQuery | ||
| product_documentation_override: https://cloud.google.com/bigquery | ||
| api_shortname_override: bigquery |
There was a problem hiding this comment.
Removing the product_documentation_override for google-cloud-bigquery results in the complete removal of the product_documentation field from .repo-metadata.json (as seen in the changes to that file). This is a significant loss of metadata for a core library. If Librarian does not provide a suitable default value, the override should be maintained.
name_pretty_override: Google Cloud BigQuery
product_documentation_override: https://cloud.google.com/bigquery
api_shortname_override: bigquery| name_pretty_override: Cloud DNS | ||
| product_documentation_override: https://cloud.google.com/dns | ||
| api_shortname_override: dns |
There was a problem hiding this comment.
Similar to the BigQuery library, removing the override for google-cloud-dns causes the product_documentation link to be removed from .repo-metadata.json. This metadata is important for tools and consoles and should be preserved if Librarian cannot find a default.
name_pretty_override: Cloud DNS
product_documentation_override: https://cloud.google.com/dns
api_shortname_override: dns| - warehouse-package-name=google-cloud-bigquery-reservation | ||
| product_documentation_override: https://cloud.google.com/bigquery/docs/reference/reservations | ||
| metadata_name_override: bigqueryreservation |
There was a problem hiding this comment.
Removing this override causes the documentation link in README.rst and .repo-metadata.json to revert to the generic BigQuery landing page, losing the specific link to the Reservations documentation. This reduces the utility of the documentation links for users of this specific package. Consider retaining the more specific override.
- warehouse-package-name=google-cloud-bigquery-reservation
product_documentation_override: https://cloud.google.com/bigquery/docs/reference/reservations
metadata_name_override: bigqueryreservation| - python-gapic-name=apigeeconnect | ||
| product_documentation_override: https://cloud.google.com/apigee/docs/hybrid/v1.4/apigee-connect | ||
| metadata_name_override: apigeeconnect |
There was a problem hiding this comment.
The removal of this override leads to a loss of specificity in the documentation links, replacing a deep link to Apigee Connect with a general Apigee landing page. This is a regression in documentation quality for this package.
- python-gapic-name=apigeeconnect
product_documentation_override: https://cloud.google.com/apigee/docs/hybrid/v1.4/apigee-connect
metadata_name_override: apigeeconnect
|
@parthea: I'm planning to regenerate this PR with a new version of Librarian once we've moved to that version of Librarian. |
1 participant
This is a version of #16791 generated with a local version of Librarian that includes googleapis/librarian#5573.
We still expect to lose documentation URIs from .repo-metadata.json files, but we shouldn't (hopefully) be removing any where there's a generated README.rst.
It would be reasonable to just review the README.rst changes.