DOC: Clarify sorting and order of categoricals and fix typo
State: closed

Without the addition in the text it‘s unclear, what `s.sort_values(inplace=True)`
should demonstrate. Show some meaningful output now. Also, when using `astype` to
contrast ordered/unordered behavior, I think it‘s clearer to use the existing,
unordered Series than to create a new one.

Fix minor typo in categorical.py.


- [x] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).



Labels:
name: Docs
name: Categorical
description: Categorical Data Type
name: Stale

Comments:
xref https://github.com/pandas-dev/pandas/issues/10715 for a discussion on limiting tracebacks.

I do sympathize and agree that having very long tracebacks in the documentation can be distract, but my primary objection with `try/except` in an ad-hoc fashion is that it can over-obscure the expected exception behavior.  
@datapythonista Sounds good in principle but I just don't want to be the guy who insanely blew up the documentation by adding estimated 400 to 500 lines of traceback, making it practically unreadable.   

So maybe we can do it just the other way round: introduce this one additional try/execpt to the 9 already existing in this tutorial and open another issue about replacing try/except constructs by (preferably shortened) tracebacks (there is a small number of try/expcepts in other pandas tutorials too). What do you think about this, @mroeschke ?
I would slightly prefer https://github.com/pandas-dev/pandas/issues/10715 addressed before adding more `try/except` patterns such that the other `try/except` patterns could be eliminated too.
just for myself a short summary of previous activity on this:

- First try: 
#10727
worked locally but broke CI
- Reversal:
#10916
reverts the above
- Second try:
#10925
didn't work either
- Upstream:
ipython/ipython#8686
more or less the same as #10727 but upstream

It's not mentioned what exactly was the error on CI (https://github.com/pandas-dev/pandas/pull/10727#issuecomment-133594091 just states "doc builds are stopping since this commit").

Today, pandas uses the upstream IPython extension instead of its local copy (#19657), so we'd
1. make a PR upstream
2. verify that pandas docs build locally with this PR
3. somehow use this updated upstream version for building the docs in CI and see if it still works. 

This last part (# 3) is not clear to me how to accomplish - any thoughts about it?
Limiting the tracebacks doesn't necessarily need to be addressed via ipython. We can also use other code directives in sphinx where we specify the output instead of being autogenerated, or maybe the python interpreter itself can be configured or monkeypatched to change the traceback behaviour.

Maybe for now you can explain in the docs about the exception instead of showing it, so we don't have the try/except or the long traceback.
> We can also use other code directives in sphinx where we specify the output instead of being autogenerated

certainly one could use just code blocks (`.. code-block:: ipython`) as done [here](https://pandas.pydata.org/docs/dev/user_guide/basics.html#comparing-array-like-objects) but in my opinion this is worse than try/except (in any case you'll need to manually adjust the command numbers to avoid such glitches where after # 68 come # 55 and 56 and then # 69:
![image](https://user-images.githubusercontent.com/19879328/188283161-5ccf09ac-4267-453b-a7c3-6f9b35fff44d.png)

<br>

My idea was more to change IPython's exception handling by [setting](https://ipython.readthedocs.io/en/stable/api/generated/IPython.core.interactiveshell.html#IPython.core.interactiveshell.InteractiveShell.set_custom_exc) a custom handler. This is rather straightforward, just want to see how to make it configurable via a parameter to `okexcept` or something. This would also cover cases where the error message stretches over more than one line (as in the concrete case here).
Converted to DRAFT until #10715 is resolved.  

(I added an optional `no_traceback` argument to the `:okexcept:` option, works fine locally, will test it on CI next week:
![image](https://user-images.githubusercontent.com/19879328/188332749-e94c6a8b-a045-453e-9151-4facfc7b208c.png))

Thanks for looking into limiting the tracebacks @StefRe! 
This pull request is stale because it has been open for thirty days with no activity. Please [update](https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#updating-your-pull-request) and respond to this comment if you're still interested in working on this.
> respond to this comment if you're still interested in working on this.

still interested but IPython seem to ignore PR at the moment (no reaction whatsoever for a month already)
> > respond to this comment if you're still interested in working on this.
> 
> still interested but IPython seem to ignore PR at the moment (no reaction whatsoever for a month already)

ok let's close for now to clear the queue.