Better readmes for all packages

builder/mypy_boto3_builder/templates/boto3-stubs/README.md.jinja2

@@ -3,6 +3,30 @@
 Mypy-friendly type annotations for `boto3` {{ boto3_version }}.
 More information can be found [here](https://github.com/vemel/mypy_boto3).
 
+## How to use
+
+Make sure you have [mypy](https://github.com/python/mypy) installed ans activated in your IDE.
+
+Install `boto3-stubs`, it will add type annotations for `boto3` package, no services included.
+
+```bash
+# install type annotations just for boto3
+pip install boto3-stubs
+
+# if you want services type annotations, install the ones you use
+# you can find a full list below
+pip install boto3-stubs[ec2, s3]
+```
+
+Use `boto3` as usual in your project and enjoy type checking.
+
+```python
+import boto3
+
+# Invalid service name, should be `dynamodb`. No worries, `mypy` will let you know.
+client = boto3.client("dynamo")
+```
+
 ## Submodules
 
 - `all` - Type annotations for all `boto3` services.

builder/mypy_boto3_builder/templates/master/README.md.jinja2

@@ -3,6 +3,47 @@
 Mypy-friendly type annotations for `boto3` {{ boto3_version }}.
 More information can be found [here](https://github.com/vemel/mypy_boto3).
 
+## How to use
+
+This package by itself is not very useful, it just gives you access to all
+underlying `boto3` services type annotations.
+
+### Type checking
+
+Make sure you have [mypy](https://github.com/python/mypy) installed ans activated in your IDE.
+
+Install `boto3-stubs` for services that you use to get type checking working.
+
+```bash
+# You can find a full list of modules below
+pip install boto3-stubs[s3, ec2]
+```
+
+Use `boto3` as usual in your project and enjoy type checking.
+
+```python
+import boto3
+
+client = boto3.client("s3")
+
+# Oh, it must be `Bucket`... Thanks, `mypy`!
+client.create_bucket(bucket="bucket")
+```
+
+### Code auto-complete
+
+Not a single Python IDE supports `Literal` type overloads yet (but in `VSCode` support is just around the corner).
+Meanwhile, to have a nice auto-complete you can explicitly set types to help your IDE to get methods, arguments etc.
+
+```python
+import boto3_name
+from mypy_boto3.ec2 import Client, ServiceResource
+
+# now you have auto-complete for methods, arguments and even return types
+client: Client = boto3.client("ec2")
+resource: ServiceResource = boto3.resource("ec2")
+```
+
 ## Submodules
 
 - `all` - Type annotations for all `boto3` services.

builder/mypy_boto3_builder/templates/service/README.md.jinja2

@@ -1,5 +1,77 @@
 # {{ service_name.pypi_name }}
 
-Mypy-friendly type annotations for `boto3` {{ boto3_version }} `{{ service_name.boto3_name }}` service.
+Mypy-friendly auto-generated type annotations for `boto3` {{ boto3_version }} `{{ service_name.boto3_name }}` service.
 More information can be found [here](https://github.com/vemel/mypy_boto3).
-{{ '' -}}
+
+## How to use
+
+### Type checking
+
+Make sure you have [mypy](https://github.com/python/mypy) installed ans activated in your IDE.
+
+Install `boto3-stubs` for `{{ service_name.boto3_name }}` service.
+
+```bash
+pip install boto3-stubs[{{service_name.pypi_name}}]
+```
+
+Use `boto3` as usual in your project and enjoy type checking.
+
+```python
+import boto3
+
+# Use this client as usual, now mypy can check if your code is valid.
+client = boto3.client("{{ service_name.boto3_name }}")
+
+# works for session as well
+session = boto3.session.Session(region="us-west-1")
+session_client = session.client("{{ service_name.boto3_name }}")
+
+{% if package.service_resource -%}
+# Do you prefer resource approach? We've got you covered!
+resource = boto3.resource("{{ service_name.boto3_name }}")
+{% endif -%}
+```
+
+### Code auto-complete
+
+Not a single Python IDE supports `Literal` type overloads yet (but in `VSCode` support is just around the corner).
+Meanwhile, to have a nice auto-complete you can explicitly set types to help your IDE to get methods, arguments etc.
+
+```python
+import boto3
+from mypy_boto3.{{ service_name.import_name }} import Client
+{% if package.service_resource -%}
+from mypy_boto3.{{ service_name.import_name }} import ServiceResource
+{% endif %}
+{% if package.paginators -%}
+{% with paginator = package.paginators[0] -%}
+from mypy_boto3.{{ service_name.import_name }}.paginator import {{ paginator.name }}
+{% endwith -%}
+{% endif -%}
+{% if package.waiters -%}
+{% with waiter = package.waiters[0] -%}
+from mypy_boto3.{{ service_name.import_name }}.waiter import {{ waiter.name }}
+{% endwith -%}
+{% endif -%}
+{{ '\n' -}}
+# now you have auto-complete for methods, arguments and even return types
+client: Client = boto3.client("{{ service_name.boto3_name }}")
+{% if package.service_resource -%}
+{{ '\n' -}}# same for resource
+resource: ServiceResource = boto3.resource("{{ service_name.boto3_name }}")
+{% endif -%}
+{% if package.paginators -%}
+{% with paginator = package.paginators[0] -%}
+{{ '\n' -}}# even for paginators
+{{ paginator.operation_name }}_paginator: {{ paginator.name }} = client.get_paginator("{{ paginator.operation_name }}")
+{% endwith -%}
+{% endif -%}
+{% if package.waiters -%}
+{% with waiter = package.waiters[0] -%}
+{{ '\n' -}}# and waiters are also annotated
+{{ waiter.waiter_name }}_waiter: {{ waiter.name }} = client.get_waiter("{{ waiter.waiter_name }}")
+{% endwith -%}
+{% endif -%}
+```
+{{ '\n' -}}