Update docs

vemel · Jan 23, 2020 · fa38304 · fa38304
1 parent 7499059
commit fa38304
Show file tree

Hide file tree

Showing 27 changed files with 252 additions and 180 deletions.
diff --git a/README.md b/README.md
@@ -58,6 +58,25 @@ you can build services index manually.
 python -m mypy_boto3
 ```
 
+If you generate `requirements.txt` from `Pipfile.lock`,  you also should build
+index manually because package installation order is not the same.
+
+```bash
+# Add boto3-stubs with services
+pipenv install 'boto3-stubs[s3,ec2]'
+
+# Generate requirements.txt file
+pipenv lock --requirements > requirements.txt
+
+...
+
+# Install pacakges to your new environment
+pip intall requirements.txt
+
+# Generate index
+python -m mypy_boto3
+```
+
 ### How to uninstall
 
 Some files are generated by service post-install scripts, so `pip` does not fully remove packages.

diff --git a/docs/README.md b/docs/README.md
@@ -2,7 +2,7 @@
 
 > Auto-generated documentation index.
 
-[![PyPI - Handsdown](https://img.shields.io/pypi/v/mypy-boto3.svg?color=blue&style=for-the-badge)](https://pypi.org/project/mypy-boto3)
+[![PyPI - mypy-boto3](https://img.shields.io/pypi/v/mypy-boto3.svg?color=blue&style=for-the-badge)](https://pypi.org/project/mypy-boto3)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mypy-boto3.svg?color=blue&style=for-the-badge)](https://pypi.org/project/mypy-boto3)
 [![Docs](https://img.shields.io/readthedocs/mypy-boto3.svg?color=blue&style=for-the-badge)](https://mypy-boto3.readthedocs.io/)
 [![Coverage](https://img.shields.io/codecov/c/github/vemel/mypy_boto3?style=for-the-badge)](https://codecov.io/gh/vemel/mypy_boto3)
@@ -55,14 +55,33 @@ This package generates a few source files depending on services that you install
 Generation is done by a post-install script, so as long as you use `pip`, `pipfile`
 or `poetry` everything should be done automatically.
 
-However, if you use any other way and notice that services stubs do not work,
+However, if you use any other way or notice that services stubs do not work,
 you can build services index manually.
 
 ```bash
 # Use this command when you add or remove service packages
 python -m mypy_boto3
 ```
 
+If you generate `requirements.txt` from `Pipfile.lock`,  you also should build
+index manually because package installation order is not the same.
+
+```bash
+# Add boto3-stubs with services
+pipenv install 'boto3-stubs[s3,ec2]'
+
+# Generate requirements.txt file
+pipenv lock --requirements > requirements.txt
+
+...
+
+# Install pacakges to your new environment
+pip intall requirements.txt
+
+# Generate index
+python -m mypy_boto3
+```
+
 ### How to uninstall
 
 Some files are generated by service post-install scripts, so `pip` does not fully remove packages.

diff --git a/docs/builder/mypy_boto3_builder/import_helpers/import_record.md b/docs/builder/mypy_boto3_builder/import_helpers/import_record.md
@@ -18,7 +18,7 @@ Helper for Python import strings.
 
 ## ImportRecord
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L13)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L11)
 
 ```python
 total_ordering
@@ -28,7 +28,7 @@ class ImportRecord():
         name: str = '',
         alias: str = '',
         min_version: Tuple[int, ...] = (3, 8),
-        fallback: Optional[ImportRecord] = None,
+        fallback: Optional['ImportRecord'] = None,
     ) -> None:
 ```
 
@@ -44,19 +44,19 @@ Helper for Python import strings.
 
 ### ImportRecord.empty
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L50)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L48)
 
 ```python
 @classmethod
-def empty() -> ImportRecord:
+def empty() -> 'ImportRecord':
 ```
 
 ### ImportRecord().get_external
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L148)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L146)
 
 ```python
-def get_external(_module_name: str) -> ImportRecord:
+def get_external(_module_name: str) -> 'ImportRecord':
 ```
 
 Get itself.
@@ -65,7 +65,7 @@ Overriden by `InternalImportRecord`.
 
 ### ImportRecord().get_local_name
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L105)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L103)
 
 ```python
 def get_local_name() -> str:
@@ -75,7 +75,7 @@ Get local import name.
 
 ### ImportRecord().is_builtins
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L111)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L109)
 
 ```python
 def is_builtins() -> bool:
@@ -85,7 +85,7 @@ Whether import is from Python `builtins` module.
 
 ### ImportRecord().is_local
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L133)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L131)
 
 ```python
 def is_local() -> bool:
@@ -95,7 +95,7 @@ Whether import is from local module.
 
 ### ImportRecord().is_standalone
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L156)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L154)
 
 ```python
 def is_standalone() -> bool:
@@ -105,7 +105,7 @@ Whether import record should not be grouped.
 
 ### ImportRecord().is_third_party
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L123)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L121)
 
 ```python
 def is_third_party() -> bool:
@@ -115,7 +115,7 @@ Whether import is from 3rd party module.
 
 ### ImportRecord().is_type_defs
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L117)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L115)
 
 ```python
 def is_type_defs() -> bool:
@@ -125,7 +125,7 @@ Whether import is from `type_defs` module.
 
 ### ImportRecord().render
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L54)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record.py#L52)
 
 ```python
 def render() -> str:

diff --git a/docs/builder/mypy_boto3_builder/import_helpers/import_record_group.md b/docs/builder/mypy_boto3_builder/import_helpers/import_record_group.md
@@ -11,7 +11,7 @@ Grouped by `source` import records for nicer rendering.
 
 ## ImportRecordGroup
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record_group.py#L12)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record_group.py#L10)
 
 ```python
 class ImportRecordGroup():
@@ -30,13 +30,13 @@ Grouped by `source` import records for nicer rendering.
 
 ### ImportRecordGroup.from_import_records
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record_group.py#L27)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record_group.py#L25)
 
 ```python
 @classmethod
 def from_import_records(
     import_records: Iterable[ImportRecord],
-) -> List[ImportRecordGroup]:
+) -> List['ImportRecordGroup']:
 ```
 
 Get groups from `ImportRecord` list.
@@ -51,7 +51,7 @@ A list of generated [ImportRecordGroup](#importrecordgroup).
 
 ### ImportRecordGroup().is_builtins
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record_group.py#L65)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_record_group.py#L63)
 
 ```python
 def is_builtins() -> bool:

diff --git a/docs/builder/mypy_boto3_builder/import_helpers/import_string.md b/docs/builder/mypy_boto3_builder/import_helpers/import_string.md
@@ -14,7 +14,7 @@ Wrapper for Python import strings.
 
 ## ImportString
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L9)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L7)
 
 ```python
 class ImportString():
@@ -45,25 +45,25 @@ import_string.render()
 
 ### ImportString.empty
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L43)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L41)
 
 ```python
 @classmethod
-def empty() -> ImportString:
+def empty() -> 'ImportString':
 ```
 
 ### ImportString.from_str
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L39)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L37)
 
 ```python
 @classmethod
-def from_str(import_string: str) -> ImportString:
+def from_str(import_string: str) -> 'ImportString':
 ```
 
 ### ImportString().master_name
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L109)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L107)
 
 ```python
 @property
@@ -74,7 +74,7 @@ Get first import string part or `builtins`.
 
 ### ImportString().render
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L100)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L98)
 
 ```python
 def render() -> str:
@@ -88,10 +88,10 @@ Ready to use import string.
 
 ### ImportString().startswith
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L68)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/import_helpers/import_string.py#L66)
 
 ```python
-def startswith(other: ImportString) -> bool:
+def startswith(other: 'ImportString') -> bool:
 ```
 
 Check if import string starts with `other`.

diff --git a/docs/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.md b/docs/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.md
@@ -11,7 +11,7 @@ Botocore docstring parser.
 
 ## DocstringParser
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.py#L29)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.py#L27)
 
 ```python
 class DocstringParser():
@@ -34,7 +34,7 @@ Botocore docstring parser.
 
 ### DocstringParser().get_arguments
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.py#L200)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.py#L198)
 
 ```python
 def get_arguments(input_string: str) -> List[Argument]:
@@ -52,7 +52,7 @@ A list of `Argument` structures.
 
 ### DocstringParser().get_return_type
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.py#L308)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/docstring_parser.py#L306)
 
 ```python
 def get_return_type(input_string: str) -> FakeAnnotation:

diff --git a/docs/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.md b/docs/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.md
@@ -12,7 +12,7 @@ Structure for parsed as dict `:type:` or `:rtype:` nested lines.
 
 ## TypeDocLine
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L9)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L7)
 
 ```python
 class TypeDocLine():
@@ -37,11 +37,11 @@ Structure for parsed as dict `:type:` or `:rtype:` nested lines.
 
 ### TypeDocLine().indented
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L35)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L33)
 
 ```python
 @property
-def indented() -> List[TypeDocLine]:
+def indented() -> List['TypeDocLine']:
 ```
 
 Get indented lines list.
@@ -52,7 +52,7 @@ A list of [TypeDocLine](#typedocline).
 
 ### TypeDocLine().render
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L55)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L53)
 
 ```python
 def render() -> str:
@@ -66,7 +66,7 @@ A string as close as possible to original.
 
 ### TypeDocLine().required
 
-[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L48)
+[[find in source code]](https://github.com/vemel/mypy_boto3/blob/master/builder/mypy_boto3_builder/parsers/docstring_parser/type_doc_line.py#L46)
 
 ```python
 @property