updating docs for the new sorting mechanisms - GH #10886
closes #10886 

I didn't notice warnings or errors associated with those modifications when building the docs.

No more `FutureWarning` either (except in a the v. 0.13 what's new, which is legit)... 
