Skip to content

chore: address product documentation in googleapis-common-protos #16841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jskeet merged 2 commits into from
Apr 28, 2026
Merged

chore: address product documentation in googleapis-common-protos #16841

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c130291
chore: address product documentation in googleapis-common-protos
jskeet Apr 28, 2026
e7cb3bb
chore: regenerate with librarian
jskeet Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions .librarian/generator-input/client-post-processing/googleapis-common-protos-docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
description: Remove inappropriate product documentation lines in googleapis-common-protos readme
url: https://github.com/googleapis/librarian/issues/5670
replacements:
- paths: [
packages/googleapis-common-protos/README.rst
]
before: "`Google APIs Common Protos`_: Lets you define and config your API service.\n\n"
after: ""
count: 1
- paths: [
packages/googleapis-common-protos/README.rst
]
before: "- `Product Documentation`_\n"
after: ""
count: 1
- paths: [
packages/googleapis-common-protos/README.rst
]
before: ".. _Google APIs Common Protos: \n"
after: ""
count: 1
- paths: [
packages/googleapis-common-protos/README.rst
]
before: ".. _Product Documentation: \n"
after: ""
count: 1
Comment thread
jskeet marked this conversation as resolved.
- paths: [
packages/googleapis-common-protos/README.rst
]
before: |
3. `Enable the Google APIs Common Protos.`_
4. `Set up Authentication.`_
after: |
3. `Set up Authentication.`_
count: 1
- paths: [
packages/googleapis-common-protos/README.rst
]
before: ".. _Enable the Google APIs Common Protos.: \n"
after: ""
count: 1
- paths: [
packages/googleapis-common-protos/README.rst
]
before: |
- Read the `Google APIs Common Protos Product documentation`_ to learn
more about the product and see How-to Guides.
after: ""
count: 1
- paths: [
packages/googleapis-common-protos/README.rst
]
before: ".. _Google APIs Common Protos Product documentation: \n"
after: ""
count: 1
Comment on lines +64 to +69
Copy link
Copy Markdown
Contributor

@parthea parthea Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m concerned about introducing additional post-processing steps at this stage of the librarian migration. Since the common protos README was previously maintained by hand, could we revert to the manual version for now? I’d prefer to wait until we have a robust way to support autogeneration for proto-only libraries rather than adding more customizations.

Copy link
Copy Markdown
Contributor Author

@jskeet jskeet Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be happy to revert to a manual version, yes - there's a lot about this file which isn't great. But how do we stop the post-processor from generating the readme?

Copy link
Copy Markdown
Contributor

@parthea parthea Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My mistake, the README is autogenerated from synthtool here: https://github.com/googleapis/synthtool/blob/ba9afbd284495433734b84686ef8ef6785c60128/synthtool/languages/python_mono_repo.py#L231-L254

To switch to a handwritten README, we would need to modify synthtool to skip this logic for proto-only libraries. Since this is an existing issue, perhaps we don't need all of the post processing here unless we want to fix it properly. In that case, the fix should be in synthtool where we skip the code below for proto-only packages

https://github.com/googleapis/synthtool/blob/ba9afbd284495433734b84686ef8ef6785c60128/synthtool/languages/python_mono_repo.py#L231-L254

Copy link
Copy Markdown
Contributor Author

@jskeet jskeet Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To switch to a handwritten README, we would need to modify synthtool to skip this logic for proto-only libraries. Since this is an existing issue, perhaps we don't need all of the post processing here unless we want to fix it properly. In that case, the fix should be in synthtool where we skip the code below for proto-only packages

I'd rather fix it "hackily" for now (with this PR), and then do it properly when we rewrite bits of synthtool in Go (and ideally remove all kinds of string replacements - including this one). Are you okay with that?

Copy link
Copy Markdown
Contributor

@parthea parthea Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ack. I see the follow up work is captured in googleapis/librarian#5670 (comment). I'll approve this so that it doesn't block the overall migration effort.

1 change: 0 additions & 1 deletion librarian.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2958,7 +2958,6 @@ libraries:
- google/logging/type
- google/rpc/context
name_pretty_override: Google APIs Common Protos
product_documentation_override: https://github.com/googleapis/googleapis/tree/master/google
client_documentation_override: https://github.com/googleapis/google-cloud-python/tree/main/packages/googleapis-common-protos
default_version: apiVersion
- name: grafeas
Expand Down
1 change: 0 additions & 1 deletion packages/googleapis-common-protos/.repo-metadata.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
"library_type": "CORE",
"name": "googleapis-common-protos",
"name_pretty": "Google APIs Common Protos",
"product_documentation": "https://github.com/googleapis/googleapis/tree/master/google",
"release_level": "stable",
"repo": "googleapis/google-cloud-python"
}
12 changes: 1 addition & 11 deletions packages/googleapis-common-protos/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,15 @@ Python Client for Google APIs Common Protos

|stable| |pypi| |versions|

`Google APIs Common Protos`_: Lets you define and config your API service.

- `Client Library Documentation`_
- `Product Documentation`_

.. |stable| image:: https://img.shields.io/badge/support-stable-gold.svg
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
.. |pypi| image:: https://img.shields.io/pypi/v/googleapis-common-protos.svg
:target: https://pypi.org/project/googleapis-common-protos/
.. |versions| image:: https://img.shields.io/pypi/pyversions/googleapis-common-protos.svg
:target: https://pypi.org/project/googleapis-common-protos/
.. _Google APIs Common Protos: https://github.com/googleapis/googleapis/tree/master/google
.. _Client Library Documentation: https://github.com/googleapis/google-cloud-python/tree/main/packages/googleapis-common-protos/summary_overview
.. _Product Documentation: https://github.com/googleapis/googleapis/tree/master/google

Quick Start
-----------
Expand All @@ -25,12 +20,10 @@ In order to use this library, you first need to go through the following steps:

1. `Select or create a Cloud Platform project.`_
2. `Enable billing for your project.`_
3. `Enable the Google APIs Common Protos.`_
4. `Set up Authentication.`_
3. `Set up Authentication.`_

.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
.. _Enable the Google APIs Common Protos.: https://github.com/googleapis/googleapis/tree/master/google
.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html

Installation
Expand Down Expand Up @@ -99,12 +92,9 @@ Next Steps

- Read the `Client Library Documentation`_ for Google APIs Common Protos
to see other available methods on the client.
- Read the `Google APIs Common Protos Product documentation`_ to learn
more about the product and see How-to Guides.
- View this `README`_ to see the full list of Cloud
APIs that we cover.

.. _Google APIs Common Protos Product documentation: https://github.com/googleapis/googleapis/tree/master/google
.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst

Logging
Expand Down
12 changes: 1 addition & 11 deletions packages/googleapis-common-protos/docs/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,15 @@ Python Client for Google APIs Common Protos

|stable| |pypi| |versions|

`Google APIs Common Protos`_: Lets you define and config your API service.

- `Client Library Documentation`_
- `Product Documentation`_

.. |stable| image:: https://img.shields.io/badge/support-stable-gold.svg
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
.. |pypi| image:: https://img.shields.io/pypi/v/googleapis-common-protos.svg
:target: https://pypi.org/project/googleapis-common-protos/
.. |versions| image:: https://img.shields.io/pypi/pyversions/googleapis-common-protos.svg
:target: https://pypi.org/project/googleapis-common-protos/
.. _Google APIs Common Protos: https://github.com/googleapis/googleapis/tree/master/google
.. _Client Library Documentation: https://github.com/googleapis/google-cloud-python/tree/main/packages/googleapis-common-protos/summary_overview
.. _Product Documentation: https://github.com/googleapis/googleapis/tree/master/google

Quick Start
-----------
Expand All @@ -25,12 +20,10 @@ In order to use this library, you first need to go through the following steps:

1. `Select or create a Cloud Platform project.`_
2. `Enable billing for your project.`_
3. `Enable the Google APIs Common Protos.`_
4. `Set up Authentication.`_
3. `Set up Authentication.`_

.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
.. _Enable the Google APIs Common Protos.: https://github.com/googleapis/googleapis/tree/master/google
.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html

Installation
Expand Down Expand Up @@ -99,12 +92,9 @@ Next Steps

- Read the `Client Library Documentation`_ for Google APIs Common Protos
to see other available methods on the client.
- Read the `Google APIs Common Protos Product documentation`_ to learn
more about the product and see How-to Guides.
- View this `README`_ to see the full list of Cloud
APIs that we cover.

.. _Google APIs Common Protos Product documentation: https://github.com/googleapis/googleapis/tree/master/google
.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst

Logging
Expand Down
Loading