Clarify documentation of iarange

[fritzo]

Fixes #542

This aims to clarify the purpose of iarange. The docs are getting a little long, so I may trim them back down when we have a dedicated tutorial. I haven't addressed context managers since that's a basic python concept outside of Pyro.

[fritzo]

@srush Thanks for pointing this out. Do these changes help?

[srush]

Yup, very clear!

Although of course a named version without indexes like:

with latent.data_group.exchangeable(data) as group, batch:
    for b in batch:
        group.x.add().observe(b)

Seems more safe to me...

[fritzo]

Ready to merge (tests timed out).

[jpchen]

theres one snag with deploying this which is that the docs track master, which means that other docs changes eg splitting LambdaPoutine into ScalePoutine + IndepPoutine will also be deployed and will be inconsistent with the release code. i suggest we wait until the next minor version/patch to deploy

[fritzo]

Good point. Now is probably a good time to release a patch that includes the fix #533.

[fritzo]

@neerajprad let's address this test timeout issue we're facing before we release a patch, so I won't have to click RESTART RESTART RESTART when we push to master 😄

[ngoodman]

and note that @null-a is updating the AIR tutorial in light of #533 (which makes AIR work better). it'd be great to have that deployed sooner than later...

[fritzo]

Ok, I suggest we cut a patch release this morning. Then @null-a can later update AIR in dev and http://pyro.ai . Since the tutorials are not included the pip package, it should be ok to release a patch first.