Add docstrings to resource actions and sub-resources

[kyleknap]

This adds lazy loaded docstrings to resource actions and sub-resources. Note that I still have yet to add docstrings identifiers, attributes, collections, and resource waiters. I just figured that splitting the work up a bit would be easier to review. There are a lot of moving parts so I figured to break it up to make it easier to follow and track feedback updates. Here are some examples of what you can do now:

import boto3

ec2 = boto3.resource('ec2')
instance = ec2.Instance('Id')

# Sub-resource
help(ec2.Instance)
# Load action
help(instance.load)
# Action         
help(instance.start)

Note that the tests won't pass till this PR gets merged: boto/botocore#642

cc @jamesls @mtdowling @rayluo

[kyleknap]

The most recent updates add docstrings to identifiers, attributes, and references. Note that tests still won't pass until all of the botocore docstring PRs are merged.

[kyleknap]

Cool. Since all of the botocore docstrings have been merged, this should be good to get reviewed. No longer relying on any outstanding PRs.

[jamesls]

I've noticed there's been a few scenarios where we need something from botocore's session. Should we start exposing some of the botocore session methods onto a boto3 session?

[kyleknap]

We could look into this. I checked on where I use the botocore session. I use it for grabbing paginator models, waiter models, and the loader. Those are pretty low level as well so I am not sure if we want to expose those quite yet. I am not sure adding these to the boto3 session is in the scope of the this pr. Thoughts?

[jamesls]

Looks good, just had a few comments.

[kyleknap]

@jamesls I updated based on feedback. I did have a comment on exposing more methods on the boto3 session. I feel we should talk more about if the methods that we would need to expose to prevent accessing the _session attribute of a boto3 session is worth adding or if it is something we would want to expose. A fair amount of the methods that I do use on the botocore session are in the grey area in terms of what is deemed internal and what is external.

[jamesls]

Looks good. I agree we should probably talk more about what methods to expose in boto3's session, so we can do that independently of this PR.