API: add 'level' kwarg to 'Index.isin' method
closes #7890

This PR adds `level` kwarg for `Index` objects as discussed (briefly in #7890):

``` python

Index.isin(iterable, level=None)
```
### Summary
- for non-`MultiIndex` classes:
  - no functional changes in the actual membership test
  - valid `level` values are `None`, `0`, `-1` and `self.name`
  - if `level` doesn't match the name, it's a `KeyError` (was `AssertionError` before)
- for `MultiIndex` classes:
  - if `level=None`, elements of `self.values` (tuples) are used
  - otherwise elements of corresponding level are used
  - valid `level` values are the same as in `MultiIndex.get_level_values` method, `-self.nlevels..(self.nlevels - 1)` plus all unique index names
### TODO
- [x] add to documentation
- [x] optimize MultiIndex case

Also, probably related to #3268
 Performance patch is in, here's a synthetic benchmark:

``` python
In [7]: idx = pd.MultiIndex.from_product([np.arange(10000), ['a', 'b', 'c']])

In [8]: timeit idx.isin(['a'], level=1)
10000 loops, best of 3: 104 µs per loop

In [9]: timeit idx.get_level_values(1).isin(['a'])
1000 loops, best of 3: 1.37 ms per loop

In [10]: timeit idx.isin([1], level=0)
1000 loops, best of 3: 1.02 ms per loop

In [11]: timeit idx.get_level_values(0).isin([1])
100 loops, best of 3: 2.84 ms per loop


```
 looks good....doc and then can merge

FYI, if you want to revise/update isin section gr8! (I would also make it a top-level, rather than below boolean indexing)
 re: doc

other than that I've already added?
 I think it makes sense to combine those 2 sections (isin of Index objects) and isin of PandasObject as they are really the same (and confusing to look in 2 sections). http://pandas-docs.github.io/pandas-docs-travis/indexing.html#indexing-with-isin

I would simply change the isin section (that I am pointing), make it a top-level (e.g. same as Boolean Indexing), them put the examples there
 I'm a bit concerned about introducing functionality of classes that themselves have not yet been described, because `Index` & `MultiIndex` sections are way below the "isin" section on containers while they probably should be introduced with the rest in `dsintro.rst`.

Although, I see some of that happening for docs on `where` that do mention `Multiindex`, so you may be ok with that, but just to be sure, are you?
 I agree with all of that

index/MultiIndex should have an intro at the top of indexing (side issue)

but I think splitting isin up (as it is now) is a bigger problem

so I would consolidate and out as a big bullet after boolean indexing 

feel free to do a short intro if u would like as well (for index/mi)
 looks good...

@jorisvandenbossche anything else?
 no, looking good!
 thanks

let's check docs after it's built and review for correctness
