CI: Format rst code blocks with blacken-docs

[tqa236]

• closes STYLE replace flake8-rst with something maintained #46865
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

[datapythonista]

What's the plan with this @tqa236? Are the problems in the CI a blocker to move forward with this?

[tqa236]

hi @datapythonista, this problem is not related to the recent broken CI, although the broken CI indeed doesn't help testing or exploring.

The exact issue that prevents us from having a green CI is just the number of new lines in some code blocks in the doc where black enforces the new lines but ipython raises a warning there, which are treated as errors per our configuration. This warning doesn't affect the build, as the rendered doc still looks correct.

The approach I'm exploring now is a way to disable this warning by passing ipython_warning_is_error=False to silent this warning while still keeping other sphinx warning.

I raised the issue here and here as well, but any quick change seems unlikely.

If you can point me to where I can pass jupyter or sphinx config to the build, it would be a great help.

[datapythonista]

Thanks for the update @tqa236.

I can't find the warnings in the doc build, are they still happening?

Configuration changes should be placed in doc/source/conf.py, I see an nbsphinx option to control the warnings: https://nbsphinx.readthedocs.io/en/0.9.3/configuration.html#suppress_warnings

I don't fully understand why ipython/nbsphinx should complain about blank lines, they shouldn't validate the style or format that I know, just execute the code. I can have a look if you can point me to the warnings that are making the CI fail, I only see an error I think I saw in other PRs about the section underlines.

CC @MarcoGorelli in case you have any opinion here.

[tqa236]

thanks for pointing me to the conf file, @datapythonista. I'm able to pass the IPython config to the sphinx build now.

Unfortunately, my approach doesn't work yet, as a warning is still raised, and sphinx will fail the build because of that.

I'll need to think of another solution.

[tqa236]

closed as I don't know how to proceed yet.