docs(general): consistency around admonitions and snippets #919

DanyC97 · 2021-12-20T20:30:55Z

Issue #, if available: #917

Description of changes:

Throughout the documentation we had a bit of inconsistency around
admonitions.

As such we added few rules to keep the consistency which will improve
the UX:

we should use ???+ instead of !!! so we can have a collapse block
(default open)
for admonitions with default title, we should write the description
on a new line
for admonitions which has a custom title as well as a description, we
should adhere to the format <admonitions type>: <custom title>.

E.g - for a tip admonitions with a custom title "Did you know?" and
description of "Powertools is a brilliant library"

???+ tip "Tip: Did you know?"
     Powertools is a brilliant library

Checklist

Meet tenets criteria
Update tests
Update docs
PR title follows conventional commit semantics

Breaking change checklist

RFC issue #:

Migration process documented
Implement warnings (if it can live side by side)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Throughout the documentation we had a bit of inconsistency around admonitions. As such we added few rules to keep the consistency which will improve the UX: * we should use `???+` instead of `!!!` so we can have a collapse block (default open) * for admonitions with default title, we should write the description on a new line * for admonitions which has a custom title as well as a description, we should adhere to the format `<admonitions type>: <custom title>`. E.g - for a tip admonitions with a custom title "Did you know?" and description of "Powertools is a brilliant library" ``` ???+ tip "Tip: Did you know?" Powertools is a brilliant library ```

codecov-commenter · 2021-12-20T20:33:02Z

Codecov Report

Merging #919 (a7a7161) into develop (cd15ee9) will increase coverage by 0.05%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           develop     #919      +/-   ##
===========================================
+ Coverage    99.90%   99.96%   +0.05%     
===========================================
  Files          118      118              
  Lines         5246     5273      +27     
  Branches       596      606      +10     
===========================================
+ Hits          5241     5271      +30     
+ Misses           1        0       -1     
+ Partials         4        2       -2

Impacted Files	Coverage Δ
...wertools/utilities/idempotency/persistence/base.py	`99.36% <0.00%> (-0.01%)`	⬇️
aws_lambda_powertools/tracing/tracer.py	`100.00% <0.00%> (ø)`
aws_lambda_powertools/shared/functions.py	`100.00% <0.00%> (ø)`
aws_lambda_powertools/event_handler/api_gateway.py	`100.00% <0.00%> (ø)`
...ws_lambda_powertools/utilities/idempotency/base.py	`100.00% <0.00%> (ø)`
...lambda_powertools/utilities/data_classes/common.py	`100.00% <0.00%> (ø)`
...wertools/utilities/data_classes/active_mq_event.py	`100.00% <0.00%> (ø)`
...wertools/utilities/data_classes/rabbit_mq_event.py	`100.00% <0.00%> (ø)`
...s/utilities/data_classes/dynamo_db_stream_event.py	`100.00% <0.00%> (ø)`
.../utilities/data_classes/code_pipeline_job_event.py	`100.00% <0.00%> (ø)`
... and 2 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cd15ee9...a7a7161. Read the comment docs.

docs/core/metrics.md

docs/utilities/parameters.md

docs/utilities/batch.md

DanyC97 · 2021-12-20T20:53:51Z

to reviewer attention:

please try to look at the batch.md by running the site local and confirm if the examples are formatted okay (in my local dev s'thing was odd)
as i got along, i've added punctuation to all the admonitions, hopefully i haven't missed any (not 100% sure though)

heitorlessa · 2021-12-22T13:15:35Z

This is awesome @DanyC97 - Once I finish the major work for the next release I'll look into this, specially render the docs locally to see how much width it covers when reading the docs.

Thank you!!!

DanyC97 · 2021-12-22T13:49:45Z

specially render the docs locally

in new year will try to see if we can have a preview docs rendered as part of PR to avoid extra work.

heitorlessa · 2021-12-30T09:15:35Z

I'm merging this today - I'm making some minor fixes to adjust for screen and things like there's no need to use ???+ for those that have one line information.

???+ info "Info: Explicit parameters take precedence over environment variables"

DanyC97 · 2021-12-30T10:25:57Z

I'm merging this today - I'm making some minor fixes to adjust for screen and things like there's no need to use ???+ for those that have one line information.

???+ info "Info: Explicit parameters take precedence over environment variables"

sure, feel free to make changes. Note the rational for having ???+ even on single lines were for consistency rather than added value

heitorlessa · 2021-12-30T11:04:20Z

Yeah I noticed that. I'll do multiple passes to see what reads better from an accessibility perspective and screen real estate.

heitorlessa · 2021-12-30T11:16:25Z

Time allowing, I'm gonna take this opportunity to use the new title in code snippets - Then we will use tabbed content when we have multiple code blocks to show.

Example - what do you think @DanyC97

heitorlessa · 2021-12-30T11:19:44Z

I've just finished playing with single line admonition vs two-line - I'll revert those changes. Thanks again for chiming in.

Reasoning: It's easier to forget to add Tip: <text> as you add docs over time. Screen real estate and accessibility doesn't change significantly

…ding

…ording

heitorlessa · 2021-12-30T17:46:09Z

Finally done :) All single snippet examples are no longer tabbed, except multiple code snippets. Also improved wording here and there part of previous PRs I didn't manage to do copywriting.

Thank you so much @DanyC97 for kicking this off! Merging

DanyC97 · 2021-12-30T18:07:27Z

Time allowing, I'm gonna take this opportunity to use the new title in code snippets - Then we will use tabbed content when we have multiple code blocks to show.

Example - what do you think @DanyC97

i love it, brilliant work!

…tools-python into complex * 'develop' of https://github.com/awslabs/aws-lambda-powertools-python: (24 commits) docs: consistency around admonitions and snippets (aws-powertools#919) chore(deps-dev): bump mypy from 0.920 to 0.930 (aws-powertools#925) fix(event-sources): handle dynamodb null type as none, not bool (aws-powertools#929) fix(apigateway): support @app.not_found() syntax & housekeeping (aws-powertools#926) docs: Added GraphQL Sample API to Examples section of README.md (aws-powertools#930) feat(idempotency): support dataclasses & pydantic models payloads (aws-powertools#908) feat(tracer): ignore tracing for certain hostname(s) or url(s) (aws-powertools#910) feat(event-sources): cache parsed json in data class (aws-powertools#909) fix(warning): future distutils deprecation (aws-powertools#921) docs(batch): remove leftover from legacy docs(layer): bump Lambda Layer to version 6 chore: bump to 1.23.0 docs(apigateway): add new not_found feature (aws-powertools#915) docs: external reference to cloudformation custom resource helper (aws-powertools#914) feat(logger): allow handler with custom kwargs signature (aws-powertools#913) chore: minor housekeeping before release (aws-powertools#912) chore(deps-dev): bump mypy from 0.910 to 0.920 (aws-powertools#903) feat(batch): new BatchProcessor for SQS, DynamoDB, Kinesis (aws-powertools#886) fix(parser): overload parse when using envelope (aws-powertools#885) fix(parser): kinesis sequence number is str, not int (aws-powertools#907) ...

…tools-python into feature/905-datetime * 'develop' of https://github.com/awslabs/aws-lambda-powertools-python: feat(feature_flags): support beyond boolean values (JSON values) (aws-powertools#804) docs: consistency around admonitions and snippets (aws-powertools#919) chore(deps-dev): bump mypy from 0.920 to 0.930 (aws-powertools#925) fix(event-sources): handle dynamodb null type as none, not bool (aws-powertools#929) fix(apigateway): support @app.not_found() syntax & housekeeping (aws-powertools#926) docs: Added GraphQL Sample API to Examples section of README.md (aws-powertools#930) feat(idempotency): support dataclasses & pydantic models payloads (aws-powertools#908) feat(tracer): ignore tracing for certain hostname(s) or url(s) (aws-powertools#910) feat(event-sources): cache parsed json in data class (aws-powertools#909) fix(warning): future distutils deprecation (aws-powertools#921)

pull-request-size bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Dec 20, 2021

boring-cyborg bot added the documentation Improvements or additions to documentation label Dec 20, 2021

DanyC97 force-pushed the fix-apigw-note-style branch from 17aa303 to d226b01 Compare December 20, 2021 20:31

DanyC97 force-pushed the fix-apigw-note-style branch from d226b01 to 8c06557 Compare December 20, 2021 20:32

DanyC97 changed the title ~~docs: Consistency around docs admonitions~~ docs: Consistency around admonitions Dec 20, 2021

DanyC97 commented Dec 20, 2021

View reviewed changes

docs/core/metrics.md Show resolved Hide resolved

DanyC97 commented Dec 20, 2021

View reviewed changes

docs/utilities/parameters.md Outdated Show resolved Hide resolved

DanyC97 commented Dec 20, 2021

View reviewed changes

docs/utilities/batch.md Outdated Show resolved Hide resolved

heitorlessa added 2 commits December 30, 2021 10:27

docs: adjust wording and unnecessary collapse

2ff5edf

docs(logger): adjust wording and unnecessary collapse

3cdc27a

docs(metrics): improve word placement on env vars

eb3534f

heitorlessa added 8 commits December 30, 2021 12:23

docs(style): make simple code expr bold

ee38dcd

revert: one-line admonition for consistency

7c56887

docs(logger): revert example due to low eyesight issue

0e2b64f

docs: revert SAM example due to low eyesight

1d28fd2

docs: address last TODOs

2a7c082

docs(homepage): use title for simple code blocks

f063550

docs(tracer): update single code blocks to title

1822ebe

docs(logger): update single code blocks to title

08e6da7

pull-request-size bot removed the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Dec 30, 2021

pull-request-size bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Dec 30, 2021

heitorlessa added 10 commits December 30, 2021 13:57

docs(metrics): update single code blocks to title

7f6d94d

docs(event_handler): update single code blocks to title

33680e4

docs(middleware): update single code blocks to title

136b977

docs(parameters): update single code blocks to title; papercuts

00c40e0

docs(batch): update single code blocks to title

585b286

docs(validation): update single code blocks to title

7822852

docs(parser): update single code blocks to title

bf6507c

docs(idempotency): update single code blocks to title; simplified wor…

a7a7161

…ding

docs(feature_flags): update single code blocks to title; simplified w…

a5685c3

…ording

docs(jmespath): update single code blocks to title

10ed9fe

heitorlessa changed the title ~~docs: Consistency around admonitions~~ docs: consistency around admonitions and snippets Dec 30, 2021

heitorlessa merged commit f985c40 into aws-powertools:develop Dec 30, 2021

heitorlessa mentioned this pull request Dec 30, 2021

feat(feature_flags): support beyond boolean values (JSON values) #804

Merged

6 tasks

heitorlessa changed the title ~~docs: consistency around admonitions and snippets~~ docs(general): consistency around admonitions and snippets Dec 31, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(general): consistency around admonitions and snippets #919

docs(general): consistency around admonitions and snippets #919

Uh oh!

DanyC97 commented Dec 20, 2021 •

edited

Loading

Uh oh!

codecov-commenter commented Dec 20, 2021 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DanyC97 commented Dec 20, 2021 •

edited

Loading

Uh oh!

heitorlessa commented Dec 22, 2021

Uh oh!

DanyC97 commented Dec 22, 2021

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

DanyC97 commented Dec 30, 2021

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

heitorlessa commented Dec 30, 2021 •

edited

Loading

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

DanyC97 commented Dec 30, 2021

Uh oh!

Uh oh!

docs(general): consistency around admonitions and snippets #919

docs(general): consistency around admonitions and snippets #919

Uh oh!

Conversation

DanyC97 commented Dec 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of changes:

Breaking change checklist

Uh oh!

codecov-commenter commented Dec 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DanyC97 commented Dec 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

heitorlessa commented Dec 22, 2021

Uh oh!

DanyC97 commented Dec 22, 2021

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

DanyC97 commented Dec 30, 2021

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

heitorlessa commented Dec 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

heitorlessa commented Dec 30, 2021

Uh oh!

DanyC97 commented Dec 30, 2021

Uh oh!

Uh oh!

DanyC97 commented Dec 20, 2021 •

edited

Loading

codecov-commenter commented Dec 20, 2021 •

edited

Loading

DanyC97 commented Dec 20, 2021 •

edited

Loading

heitorlessa commented Dec 30, 2021 •

edited

Loading