DOC: Clarify sorting and order of categoricals and fix typo

[StefRe]

trafficstars

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.

[mroeschke]

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.

[StefRe]

@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 ?

[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.

[StefRe]

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?

[datapythonista]

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.

[StefRe]

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 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:

My idea was more to change IPython's exception handling by setting 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).

[StefRe]

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: )

[mroeschke]

Thanks for looking into limiting the tracebacks @StefRe!