Skip to content
This repository was archived by the owner on Mar 31, 2026. It is now read-only.

docs: streamline docstrings for conditional parmas - #464

Merged
tseaver merged 6 commits into
masterfrom
460-move-boilerplate-gen-metagen-docs-from-docstrings
Jun 21, 2021
Merged

docs: streamline docstrings for conditional parmas#464
tseaver merged 6 commits into
masterfrom
460-move-boilerplate-gen-metagen-docs-from-docstrings

Conversation

@tseaver

@tseavertseaver commented Jun 10, 2021•
edited
Loading

Copy link
Copy Markdown
Contributor

Add narrative docs for conditional params:

  • 'if_generation_match'
  • 'if_generation_not_match'
  • 'if_metageneration_match'
  • 'if_metageneration_not_match'

Replace verbose docstring entries for those params with links to the narrative docs.

Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.

Closes#460.

@tseaver
tseaver requested review from a team, andrewsg, cojenco, frankyn and tritoneJune 10, 2021 18:42
@product-auto-labelproduct-auto-labelBot added the api: storage Issues related to the googleapis/python-storage API. label Jun 10, 2021
@google-clagoogle-claBot added the cla: yes This human has signed the Contributor License Agreement. label Jun 10, 2021
This was referenced Jun 11, 2021
Merged
Merged
@tseavertseaver added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jun 11, 2021
@tseaver

tseaver commented Jun 11, 2021•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Blocked pending merges of:

@tseaver
tseaverforce-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from d8ad3ee to 1b2ef92CompareJune 14, 2021 15:52
@tseavertseaver removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jun 14, 2021
@tseaver
tseaverforce-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from 1b2ef92 to 0d296b0CompareJune 15, 2021 17:19
@tseavertseaver added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 18, 2021
@yoshi-kokoroyoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 18, 2021
@tseaver

tseaver commented Jun 18, 2021

Copy link
Copy Markdown
ContributorAuthor

@cojenco, @andrewsg ready for review.

@tseaver
docs: add narrative docs for conditional params
c502a92
- 'if_genration_match'
- 'if_genration_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'
Toward #460.
@tseaver
docs: streamline docstrings for conditional parmas
7c04114
Link to new narrative docs.
Also, move 'timeout' argument to end (just before 'retry', if present)
for consistency.
Closes#460.
@tseaver
tseaverforce-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from 4a8fa65 to 7c04114CompareJune 21, 2021 17:01
@tseaver

tseaver commented Jun 21, 2021

Copy link
Copy Markdown
ContributorAuthor

@frankyn, @tritone, @andrewsg, @cojenco PTAL.

@cojenco

cojenco commented Jun 21, 2021

Copy link
Copy Markdown
Contributor

Thanks for the ping, @tseaver . Taking a look now.

cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
Comment threaddocs/generation_metageneration.rst Outdated
cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
Comment threaddocs/generation_metageneration.rst Outdated
cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
Comment threaddocs/generation_metageneration.rst Outdated
cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
Comment threaddocs/generation_metageneration.rst Outdated
cojenco
cojenco suggested changes Jun 21, 2021
View reviewed changes

@cojencocojenco left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks @tseaver for adding the generation/preconditions reference doc and streamlining the docstrings. Looks so much better! A few comments and nits, otherwise, LGTM

@tseaver
docs: add prologue, linking concepts
b9367f4
Addressing review comment.
@tseaver
docs: wording changes / typo fixes
e8f2479
Addressing review comments.
@tseaver
tseaver requested a review from cojencoJune 21, 2021 18:32
cojenco
cojenco approved these changes Jun 21, 2021
View reviewed changes

@cojencocojenco left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM, thanks!

danielduhh
danielduhh reviewed Jun 21, 2021
View reviewed changes

@danielduhhdanielduhh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Just one super nit -- also looks like Kokoro is failing

Comment threaddocs/generation_metageneration.rst Outdated
@dandhlee

dandhlee commented Jun 21, 2021

Copy link
Copy Markdown
Contributor

docfx and docs-presubmit will fail, sorry about that! If if's just those two and you can move the PR along then please do so, otherwise you'll have to wait until I resolve it with googleapis/sphinx-docfx-yaml#48.

@dandhleedandhlee added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 21, 2021
@yoshi-kokoroyoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 21, 2021
@dandhlee

dandhlee commented Jun 21, 2021

Copy link
Copy Markdown
Contributor

Everything is fixed! Sorry to make you wait 😅

@tseaver
tseaver merged commit 6999370 into masterJun 21, 2021
@tseaver
tseaver deleted the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch June 21, 2021 22:31
cojenco pushed a commit to cojenco/python-storage that referenced this pull request Oct 13, 2021
@tseaver@cojenco
docs: streamline docstrings for conditional parmas (googleapis#464)
506e883
Add narrative docs for conditional params:
- 'if_generation_match'
- 'if_generation_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'
Streamline docstrings for conditional params, linking to new narrative docs.
Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.
Closesgoogleapis#460.
cojenco pushed a commit to cojenco/python-storage that referenced this pull request Oct 13, 2021
@tseaver@cojenco
docs: streamline docstrings for conditional parmas (googleapis#464)
04dd1e3
Add narrative docs for conditional params:
- 'if_generation_match'
- 'if_generation_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'
Streamline docstrings for conditional params, linking to new narrative docs.
Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.
Closesgoogleapis#460.
Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@andrewsgandrewsgAwaiting requested review from andrewsg
@frankynfrankynAwaiting requested review from frankyn
@tritonetritoneAwaiting requested review from tritone
2 more reviewers
@danielduhhdanielduhhdanielduhh left review comments
@cojencocojencocojenco approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

api: storageIssues related to the googleapis/python-storage API.cla: yesThis human has signed the Contributor License Agreement.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Move boilerplate docs for 'if_generation_match' et al. out of method docstrings

5 participants

@tseaver@cojenco@dandhlee@danielduhh@yoshi-kokoro