Skip to content

docs: Adds links related to logging samples in README.rst.j2 #2570

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

Open
chalmerlowe wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Adds links related to logging samples in README.rst.j2 #2570

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 14 additions & 0 deletions gapic/templates/README.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,3 +141,17 @@ Logging details
#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get
executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured.
(This is the reason for 2.i. above.)


Additional information
~~~~~~~~~~~~~~~~~~~~~~

For additional information and examples about logging see:

- `Logging Docs`_
- `Generated samples`_
- `Additional samples`_

.. _Logging Docs: https://docs.cloud.google.com/logging/docs
.. _Generated samples: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging/samples/generated_samples
.. _Additional samples: https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/logging
Comment on lines +146 to +157
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 25, 2026

Choose a reason for hiding this comment

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

high

This template file, README.rst.j2, is a generic template used to generate README.rst files for all Python client libraries. The links you've added are specific to google-cloud-logging.

By adding them to this shared template, these logging-specific links will incorrectly appear in the READMEs of all other client libraries (e.g., Translate, Vision, etc.), which will be confusing for users of those libraries.

If these links are only relevant for the logging library, they should be added conditionally. For example, using a Jinja if block (the exact variable may differ):

{% if 'logging' in api.name %}
Additional information
~~~~~~~~~~~~~~~~~~~~~~

For additional information and examples about logging see:

- `Logging Docs`_
- `Generated samples`_
- `Additional samples`_

.. _Logging Docs: https://docs.cloud.google.com/logging/docs
.. _Generated samples: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging/samples/generated_samples
.. _Additional samples: https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/logging
{% endif %}

If a conditional approach isn't feasible, these links should be removed from this common template to avoid generating incorrect documentation for other libraries.

References
  1. For generated code, apply fixes to the generator templates rather than patching individual output files to ensure consistency across the codebase.

Copy link
Contributor Author

@chalmerlowe chalmerlowe Feb 25, 2026

Choose a reason for hiding this comment

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

@gemini-code-assist if we look at the context around these three links, we will see that this entire section of the readme is devoted to how to use logging with any client library (i.e. Translate, Vision, etc). This PR adds links for the customer to learn more about how they can apply logging, so this addition is both universal and highly relevant to this section.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 25, 2026

Choose a reason for hiding this comment

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

You're right that the preceding section discusses general logging configurations applicable to any client library. However, the specific links you've added for "Generated samples" and "Additional samples" point directly to the google-cloud-logging Python client library's samples.

Since this README.rst.j2 is a generic template, these logging-specific sample links will appear in the READMEs of all generated client libraries (e.g., Translate, Vision, etc.). This would be misleading and confusing for users of those other libraries, as the links would not be relevant to their specific client library.

To maintain the universal applicability of this section, I recommend one of two approaches:

  1. Make the sample links conditional: As suggested previously, wrap the sample links in a Jinja if block that only renders them for the google-cloud-logging library.
  2. Remove the logging-specific sample links: Keep only the general "Logging Docs" link, which is universally relevant. This would look like this:
Additional information
~~~~~~~~~~~~~~~~~~~~~~

For additional information and examples about logging see:

- `Logging Docs`_

.. _Logging Docs: https://docs.cloud.google.com/logging/docs

This ensures that the generated READMEs for all client libraries provide accurate and relevant information.

Loading