Instead, could you show this as an example in the Examples section instead?

I'll probably be removing the warning but I could show an example

@mroeschke - good here?

This is only true when append=False. As mentioned in the issue, this seems to me to be redundant with the line above:

The index can replace the existing index or expand on it.

Thanks for the review. Though it seems redundant with the line you mentioned. When you look at,

append: bool, default False

Whether to append columns to existing index.

it doesn't directly explain the behavior of replacing the existing index (by default). Does this statement makes it clear?

append: bool, default False

Whether to append new columns to the existing index . If set to True, the current index will remain unchanged and new columns will be added.

Agreed we should add something here, but saying it is unchanged and columns are added seems inconsistent to me. I also think the True behavior is already clear by Whether to append new columns to the existing index. However the False behavior could perhaps use elaboration. I would suggest:

When False, the current index will be dropped from the DataFrame.

But not strongly opposed to adding elaboration for the True case either.

We will be deprecating inplace in the near-ish future. Can you do df = df.set_index(...) instead.

Sure do!!

I had suggested df. I would stay away from a as it has no particular meeting. Is there a reason to not use df here?

I thought not to disturb the original dataframe.

Nevertheless, I've updated to df.