DOC: Don't show traceback for :okexcept:
State: closed

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](https://github.com/docutils/docutils/blob/bc9bf5fc2c7f905507a49e8e37c12368c2f4a0cc/docutils/docutils/parsers/rst/__init__.py#L325). 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 https://github.com/ipython/ipython/pull/13751
gets merged upstream.

Example of the new docs including correct syntax highlighting with the `no_traceback` option:
![image](https://user-images.githubusercontent.com/19879328/204130429-436a4693-fbe3-4b06-b85e-b7145573a702.png)


<hr>  

- [x] closes #10715
- [N/A] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [x] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [N/A] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) 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.


Labels:
name: Docs
name: Error Reporting
description: Incorrect or improved errors from pandas
name: Mothballed
description: Temporarily-closed PR the author plans to return to

Comments:
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](https://github.com/pandas-dev/pandas/suites/8178161548/artifacts/355639929):
![image](https://user-images.githubusercontent.com/19879328/188960568-f1dfdaad-5d0e-4b9f-8ef3-6d446076be80.png)
  
I made a [minimal example](https://github.com/StefRe/no_traceback) 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`:
![image](https://user-images.githubusercontent.com/19879328/188962467-6acecf99-23bd-4afc-a101-433d771ff510.png)). 

Any thoughts on this @mroeschke? Would it be OK to have the error message without color formatting?
> 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
I found the culprit: [`IPython.sphinxext.ipython_console_highlighting`](https://github.com/pynbody/pynbody/blob/master/docs/sphinxext/ipython_console_highlighting.py) uses [`IPyLexer`](https://github.com/ipython/ipython/blob/84af48129c748341ce0b73cb42d310fc7966a51a/IPython/lib/lexers.py#L490) to highlight the code *and the traceback*. A traceback is recognized with the [following regex](https://github.com/ipython/ipython/blob/84af48129c748341ce0b73cb42d310fc7966a51a/IPython/lib/lexers.py#L259):
``` python
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:

``` python
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')
```

![grafik](https://user-images.githubusercontent.com/19879328/189122729-362edfd1-3bb2-4111-8195-f7c56ddebfb3.png)

> 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?
> Do you think this is something that can fixed upstream in iPython?

Let's see if https://github.com/ipython/ipython/pull/13751 gets merged.
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.
> 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.

Yes, still interested in it.  Rebased onto current master. Waiting for https://github.com/ipython/ipython/pull/13751 to be reviewed.
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.
> 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.

Yes, still interested in it.  Rebased onto current master. Waiting for https://github.com/ipython/ipython/pull/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.
As the PR https://github.com/ipython/ipython/pull/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 https://github.com/pandas-dev/pandas/pull/46624 be included back into https://github.com/pandas-dev/pandas/tree/main/doc/sphinxext?
2) Update https://github.com/pandas-dev/pandas/pull/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.
Since this PR is pending on https://github.com/ipython/ipython/pull/13751, going to close this for now and we can reopen when that PR is accepted