DOC: Don't show traceback for :okexcept:

[StefRe]

Draft to see if docs build on CI

• use local modified ipython_directive to add optional no_traceback
  argument to :ok_except: which prevents the (sometimes long) traceback
  from being printed (default is no argument, i.e. the traceback is
  printed) and enable the @okexcept pseudodecorator so that it can be
  applied to individual instructions instead of the whole block
• use local modified ipython_console_highlighting to enable syntax
  highlighting of exceptions without a traceback
• fix pylint warnings for ipython_directive.py and simplify
  "".join(["."] * x) to "." * x

The # noqa: E999 after @okexcept no_traceback is necessary to
prevent flake8-rst from complaining about syntax errors as it
interprets the pseudodecorator as a real python decorator.

In ipython_directive.py:1106, pylint complains about access to
self.content before its definition although it is defined in the base
class. That's why I added # pylint: disable=access-member-before-definition
to make the pre-commit hook pass.

Items 1 and 2 can be reverted if ipython/ipython#13751
gets merged upstream.

Example of the new docs including correct syntax highlighting with the no_traceback option:

---

• closes DOC: limit error traceback to one line for expected exceptions #10715
• [N/A] Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• [N/A] Added type annotations to new arguments/methods/functions.
• [N/A] Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

[StefRe]

Seems to work, the only thing I don't understand is why we don't get the color output for the exception class, see the created docs artifact:

I made a minimal example and the error message gets nicely formatted according to the chosen theme (I also tested the example with sphinx 4.5.0 (used on CI) instead of 5.1.1 and with the pydata_sphinx_theme:
).

Any thoughts on this @mroeschke? Would it be OK to have the error message without color formatting?

[mroeschke]

Would it be OK to have the error message without color formatting?

Yeah I think it would be fine if there was no color to start. Could be addressed later

[StefRe]

I found the culprit: IPython.sphinxext.ipython_console_highlighting uses IPyLexer to highlight the code and the traceback. A traceback is recognized with the following regex:

ipytb_start = re.compile(r'^(\^C)?(-+\n)|^(  File)(.*)(, line )(\d+\n)')

So this will need to be changed to something like this to work for exceptions without preceding traceback:

import builtins

exceptions = [name for name, value in builtins.__dict__.items() if isinstance(value, type) and issubclass(value, Exception) and not issubclass(value, Warning)]
ipytb_start = re.compile(r'^(\^C)?(-+\n)|^(  File)(.*)(, line )(\d+\n)|^(' + '|'.join(exceptions) + '): \S.*\n')

[mroeschke]

So this will need to be changed to something like this to work for exceptions without preceding traceback:

Do you think this is something that can fixed upstream in iPython?

[StefRe]

Do you think this is something that can fixed upstream in iPython?

Let's see if ipython/ipython#13751 gets merged.

[datapythonista]

Thanks @StefRe, really nice. lgtm, let's see if we can get the changes merged upstream

[github-actions]

This pull request is stale because it has been open for thirty days with no activity. Please update and respond to this comment if you're still interested in working on this.

[StefRe]

Please update and respond to this comment if you're still interested in working on this.

Yes, still interested in it. Rebased onto current master. Waiting for ipython/ipython#13751 to be reviewed.

[github-actions]

This pull request is stale because it has been open for thirty days with no activity. Please update and respond to this comment if you're still interested in working on this.

[StefRe]

Please update and respond to this comment if you're still interested in working on this.

Yes, still interested in it. Rebased onto current master. Waiting for ipython/ipython#13751 to be reviewed.
IPython appears to igonore any PR from outside their organization: since this PR of Sep 8, 31 other PR were merged, practically all of them from IPython's organization with the exception of minor fixes of typos in the docs etc. So I'm not sure if it makes sense to keep waiting for review of this PR.

[StefRe]

As the PR ipython/ipython#13751 to update the ipython_directive and ipython_console_highlighting in IPython doesn't seem to be merged or even reviewed anytime soon, I suggest using vendored versions of these directives. Is this OK with you?

If so, my plan is to:

1. Remove the changes to categorical.rst from this PR so that this PR covers only the directives and can be easily reverted if the PR in IPython should be merged.
   Should the text about these directives removed in Remove references to previously-vendored Sphinx extensions #46624 be included back into https://github.com/pandas-dev/pandas/tree/main/doc/sphinxext?
2. Update DOC: Clarify sorting and order of categoricals and fix typo #47846 using the no_traceback option.
3. Make a new PR to replace try/except blocks and static code blocks with :ok_except: and add no_traceback to existing :ok_except: cases with long tracebacks.

[mroeschke]

Since this PR is pending on ipython/ipython#13751, going to close this for now and we can reopen when that PR is accepted