docs: update usage guide for v3.0.0 by daniel-sanche · Pull Request #456 · googleapis/python-logging

daniel-sanche · 2021-12-10T23:40:32Z

This PR contains two major docs changes in prep for v3.0.0:

a major re-write of the usage guide, documenting everything I learned while working with the library over the last year
an UPGRADING.md update to describe major/breaking changes

The upgrading guide can be rendered here on GitHub. To render the usage guide locally, run the following commands:

cd python-logging
nox -s docs
cd docs/_build_html
python3 -m http.server 8085

snippet-bot · 2021-12-10T23:40:38Z

Here is the summary of possible violations 😱

Details

There are 38 possible violations for not having product prefix.

docs/direct-lib-usage.rst:23, tag usage_client_setup
docs/direct-lib-usage.rst:30, tag usage_http_client_setup
docs/direct-lib-usage.rst:42, tag logger_create
docs/direct-lib-usage.rst:51, tag logger_custom_labels
docs/direct-lib-usage.rst:63, tag logger_custom_resource
docs/direct-lib-usage.rst:74, tag logger_log_basic
docs/direct-lib-usage.rst:82, tag logger_log_fields
docs/direct-lib-usage.rst:103, tag logger_log_batch
docs/direct-lib-usage.rst:110, tag logger_log_batch_context
docs/direct-lib-usage.rst:124, tag client_list_entries_default
docs/direct-lib-usage.rst:145, tag client_list_entries_filter
docs/direct-lib-usage.rst:152, tag client_list_entries_order_by
docs/direct-lib-usage.rst:159, tag logger_list_entries
docs/direct-lib-usage.rst:180, tag logger_delete
docs/direct-lib-usage.rst:194, tag client_list_metrics
docs/direct-lib-usage.rst:201, tag metric_create
docs/direct-lib-usage.rst:208, tag metric_reload
docs/direct-lib-usage.rst:215, tag metric_update
docs/direct-lib-usage.rst:222, tag metric_delete
docs/direct-lib-usage.rst:244, tag sink_bucket_permissions
docs/direct-lib-usage.rst:251, tag sink_storage_create
docs/direct-lib-usage.rst:267, tag sink_dataset_permissions
docs/direct-lib-usage.rst:274, tag sink_bigquery_create
docs/direct-lib-usage.rst:290, tag sink_topic_permissions
docs/direct-lib-usage.rst:297, tag sink_pubsub_create
docs/direct-lib-usage.rst:307, tag client_list_sinks
docs/direct-lib-usage.rst:314, tag sink_reload
docs/direct-lib-usage.rst:321, tag sink_update
docs/direct-lib-usage.rst:328, tag sink_delete
docs/std-lib-integration.rst:32, tag create_cloud_handler
samples/snippets/usage_guide.py:106, tag usage_client_setup
samples/snippets/usage_guide.py:114, tag usage_http_client_setup
samples/snippets/usage_guide.py:133, tag logger_custom_labels
samples/snippets/usage_guide.py:138, tag logger_custom_resource
samples/snippets/usage_guide.py:149, tag logger_log_basic
samples/snippets/usage_guide.py:153, tag logger_log_fields
samples/snippets/usage_guide.py:188, tag logger_log_batch
samples/snippets/usage_guide.py:195, tag logger_log_batch_context

The end of the violation section. All the stuff below is FYI purposes only.

Here is the summary of changes.

You are about to add 47 region tags.

docs/direct-lib-usage.rst:23, tag usage_client_setup
docs/direct-lib-usage.rst:30, tag usage_http_client_setup
docs/direct-lib-usage.rst:42, tag logger_create
docs/direct-lib-usage.rst:51, tag logger_custom_labels
docs/direct-lib-usage.rst:63, tag logger_custom_resource
docs/direct-lib-usage.rst:74, tag logger_log_basic
docs/direct-lib-usage.rst:82, tag logger_log_fields
docs/direct-lib-usage.rst:103, tag logger_log_batch
docs/direct-lib-usage.rst:110, tag logger_log_batch_context
docs/direct-lib-usage.rst:124, tag client_list_entries_default
docs/direct-lib-usage.rst:145, tag client_list_entries_filter
docs/direct-lib-usage.rst:152, tag client_list_entries_order_by
docs/direct-lib-usage.rst:159, tag logger_list_entries
docs/direct-lib-usage.rst:169, tag logging_list_gke_audit_logs
docs/direct-lib-usage.rst:180, tag logger_delete
docs/direct-lib-usage.rst:194, tag client_list_metrics
docs/direct-lib-usage.rst:201, tag metric_create
docs/direct-lib-usage.rst:208, tag metric_reload
docs/direct-lib-usage.rst:215, tag metric_update
docs/direct-lib-usage.rst:222, tag metric_delete
docs/direct-lib-usage.rst:244, tag sink_bucket_permissions
docs/direct-lib-usage.rst:251, tag sink_storage_create
docs/direct-lib-usage.rst:267, tag sink_dataset_permissions
docs/direct-lib-usage.rst:274, tag sink_bigquery_create
docs/direct-lib-usage.rst:290, tag sink_topic_permissions
docs/direct-lib-usage.rst:297, tag sink_pubsub_create
docs/direct-lib-usage.rst:307, tag client_list_sinks
docs/direct-lib-usage.rst:314, tag sink_reload
docs/direct-lib-usage.rst:321, tag sink_update
docs/direct-lib-usage.rst:328, tag sink_delete
docs/std-lib-integration.rst:15, tag logging_handler_setup
docs/std-lib-integration.rst:32, tag create_cloud_handler
docs/std-lib-integration.rst:54, tag logging_handler_usage
docs/std-lib-integration.rst:73, tag logging_extra_json_fields
docs/std-lib-integration.rst:80, tag logging_json_dumps
docs/std-lib-integration.rst:116, tag logging_extras
samples/snippets/usage_guide.py:106, tag usage_client_setup
samples/snippets/usage_guide.py:114, tag usage_http_client_setup
samples/snippets/usage_guide.py:133, tag logger_custom_labels
samples/snippets/usage_guide.py:138, tag logger_custom_resource
samples/snippets/usage_guide.py:149, tag logger_log_basic
samples/snippets/usage_guide.py:153, tag logger_log_fields
samples/snippets/usage_guide.py:188, tag logger_log_batch
samples/snippets/usage_guide.py:195, tag logger_log_batch_context
samples/snippets/usage_guide.py:437, tag logging_json_dumps
samples/snippets/usage_guide.py:445, tag logging_extra_json_fields
samples/snippets/usage_guide.py:457, tag logging_extras

You are about to delete 30 region tags.

docs/usage.rst:12, tag logger_create
docs/usage.rst:19, tag logger_log_text
docs/usage.rst:26, tag logger_log_struct
docs/usage.rst:38, tag logger_log_resource_text
docs/usage.rst:48, tag client_list_entries_default
docs/usage.rst:69, tag client_list_entries_filter
docs/usage.rst:76, tag client_list_entries_order_by
docs/usage.rst:83, tag logger_list_entries
docs/usage.rst:93, tag logging_list_gke_audit_logs
docs/usage.rst:101, tag logger_delete
docs/usage.rst:115, tag client_list_metrics
docs/usage.rst:122, tag metric_create
docs/usage.rst:129, tag metric_reload
docs/usage.rst:136, tag metric_update
docs/usage.rst:143, tag metric_delete
docs/usage.rst:165, tag sink_bucket_permissions
docs/usage.rst:172, tag sink_storage_create
docs/usage.rst:188, tag sink_dataset_permissions
docs/usage.rst:195, tag sink_bigquery_create
docs/usage.rst:211, tag sink_topic_permissions
docs/usage.rst:218, tag sink_pubsub_create
docs/usage.rst:228, tag client_list_sinks
docs/usage.rst:235, tag sink_reload
docs/usage.rst:242, tag sink_update
docs/usage.rst:249, tag sink_delete
docs/usage.rst:262, tag create_default_handler
docs/usage.rst:273, tag setup_logging
docs/usage.rst:285, tag setup_logging_excludes
docs/usage.rst:299, tag create_cloud_handler
docs/usage.rst:315, tag create_named_handler

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

Refresh this comment

losalex

As we spoke earlier, this should be reviewed by writers as well

arbrown · 2022-01-11T17:55:26Z

cd docs/_build_html

This directory was cd docs/_build/html on my machine. Not sure if it was a nox config issue or a typo.

arbrown

Minor nits on pre-existing docs, otherwise looks good!

daniel-sanche added 15 commits December 7, 2021 15:45

added empty v3.0.0 section to UPGRADING.md
a5c36d7

reorganized table of contents
0ff7048

marked old handlers as deprecated
68e7f9d

removed duplicated stdlib doc
ff046f5

made some progress on standard library integration doc
2e5fd18

added more stdlib documentation
51d2a9a

finished up stdlib docs
fcc239b

added page for direct API usage
5826ce3

copied old usage guide info
205d915

working on setup section
98a0a8c

added log writing docs
117e619

removed references to POST requests
913a08c

added batching info
29ea7d4

added transport docs
e822bd0

added grpc vs http docs
8bce609

product-auto-labelBot added the api: logging Issues related to the googleapis/python-logging API. label Dec 10, 2021

daniel-sanche force-pushed the v3_usage_guide branch 6 times, most recently from 8c7f10e to 3184972Compare December 15, 2021 00:28

added upgrading notes
eac5e2d

daniel-sanche force-pushed the v3_usage_guide branch from 3184972 to eac5e2dCompare December 15, 2021 00:34

daniel-sanche changed the title ~~[WIP] docs: update usage guide for v3.0.0~~docs: update usage guide for v3.0.0Dec 15, 2021

daniel-sanche marked this pull request as ready for review December 15, 2021 01:11

daniel-sanche requested a review from a teamDecember 15, 2021 01:11

daniel-sanche requested a review from a team as a code owner December 15, 2021 01:11

daniel-sanche requested a review from a teamDecember 15, 2021 01:11

daniel-sanche requested review from busunkim96 and removed request for a teamDecember 15, 2021 01:11

losalex approved these changes Dec 16, 2021
View reviewed changes

product-auto-labelBot added the stale: old Pull request is old and needs attention. label Jan 10, 2022

arbrown approved these changes Jan 11, 2022
View reviewed changes

Comment threaddocs/direct-lib-usage.rst Outdated
Comment threaddocs/direct-lib-usage.rst Outdated
Comment threaddocs/direct-lib-usage.rst Outdated

improved manual handler section
01a0e33

product-auto-labelBot added the size: xl Pull request size is extra large. label Jan 14, 2022

daniel-sanche added 11 commits January 14, 2022 16:14

fixed lint issues
0526955

fixed snippet issue
a91b5f4

addressed Drew's comments
0ad37c8

incorporated Pamela's feedback to migration guide
fd314b9

updated formatting
95e5890

updated wording
51a7cd5

changed wording
69209b1

addressed Pamela's comments on the direct library usage document
741dfac

incorporated Pamela's feedback in std lib integration doc
49dc3c3

removed unneeded delete lines
ef947d3

switched client for tests
1ff01aa

daniel-sanche merged commit 151a378 into v3.0.0Jan 26, 2022

daniel-sanche deleted the v3_usage_guide branch January 26, 2022 22:16

daniel-sanche mentioned this pull request Jan 26, 2022
chore: merge v3.0.0 staging branch into main #455
Merged

daniel-sanche added a commit that referenced this pull request Jan 27, 2022
docs: update usage guide for v3.0.0 (#456)
8266de1

daniel-sanche added a commit that referenced this pull request Jan 27, 2022
docs: update usage guide for v3.0.0 (#456)
8a67b73

release-pleaseBot mentioned this pull request Jan 27, 2022
chore(main): release 3.0.0 #473
Merged

Navigation Menu

Uh oh!

docs: update usage guide for v3.0.0 - #456

docs: update usage guide for v3.0.0#456
daniel-sanche merged 28 commits into
v3.0.0from
v3_usage_guide

daniel-sanche commented Dec 10, 2021•
edited
Loading

Uh oh!

snippet-botBot commented Dec 10, 2021•
edited
Loading

Uh oh!

losalex left a comment

Uh oh!

arbrown commented Jan 11, 2022

Uh oh!

arbrown left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

daniel-sanche commented Dec 10, 2021• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snippet-botBot commented Dec 10, 2021• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

losalex left a comment

Choose a reason for hiding this comment

Uh oh!

arbrown commented Jan 11, 2022

Uh oh!

arbrown left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

daniel-sanche commented Dec 10, 2021•
edited
Loading

snippet-botBot commented Dec 10, 2021•
edited
Loading