Skip to content
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.

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

docs: streamline docstrings for conditional parmas #464

Merged
merged 6 commits into from Jun 21, 2021

Conversation

@tseaver
Copy link
Contributor

@tseaver tseaver commented Jun 10, 2021

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
Copy link
Contributor Author

@tseaver tseaver commented Jun 11, 2021

Blocked pending merges of:

@tseaver tseaver force-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from d8ad3ee to 1b2ef92 Jun 14, 2021
@tseaver tseaver force-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from 1b2ef92 to 0d296b0 Jun 15, 2021
@tseaver
Copy link
Contributor Author

@tseaver tseaver commented Jun 18, 2021

@cojenco, @andrewsg ready for review.

tseaver added 2 commits Jun 21, 2021
- 'if_genration_match'
- 'if_genration_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'

Toward #460.
Link to new narrative docs.

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

Closes #460.
@tseaver tseaver force-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from 4a8fa65 to 7c04114 Jun 21, 2021
@tseaver
Copy link
Contributor Author

@tseaver tseaver commented Jun 21, 2021

@cojenco
Copy link
Contributor

@cojenco cojenco commented Jun 21, 2021

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

docs/generation_metageneration.rst Outdated Show resolved Hide resolved
docs/generation_metageneration.rst Outdated Show resolved Hide resolved
docs/generation_metageneration.rst Outdated Show resolved Hide resolved
docs/generation_metageneration.rst Outdated Show resolved Hide resolved
Copy link
Contributor

@cojenco cojenco left a comment

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 added 2 commits Jun 21, 2021
Addressing review comment.
Addressing review comments.
@tseaver tseaver requested a review from cojenco Jun 21, 2021
Copy link
Contributor

@cojenco cojenco left a comment

LGTM, thanks!

Copy link

@danielduhh danielduhh left a comment

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

docs/generation_metageneration.rst Outdated Show resolved Hide resolved
@dandhlee
Copy link
Contributor

@dandhlee dandhlee commented Jun 21, 2021

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.

@dandhlee
Copy link
Contributor

@dandhlee dandhlee commented Jun 21, 2021

Everything is fixed! Sorry to make you wait 😅

@tseaver tseaver merged commit 6999370 into master Jun 21, 2021
6 checks passed
@tseaver tseaver deleted the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch Jun 21, 2021
cojenco added a commit to cojenco/python-storage that referenced this issue Oct 13, 2021
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.

Closes googleapis#460.
cojenco added a commit to cojenco/python-storage that referenced this issue Oct 13, 2021
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.

Closes googleapis#460.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

5 participants