'autodoc-process-docstring' threw an exception (exception: The frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.)

[ns-rse]

I've encountered this exception using the current docutils-0.20.1

[AutoAPI] Adding AutoAPI TOCTree [autoapi/index] to index.rst
/tmp/tmpiodbjbom/d819d1f3d0bed977cdfa926fb309a76a8e394462/docs/autoapi/topostats/tracing/dnatracing/index.rst:368: WARNING: Block quote ends without a blank line; unexpected unindent.
/tmp/tmpiodbjbom/d819d1f3d0bed977cdfa926fb309a76a8e394462/docs/autoapi/topostats/tracing/skeletonize/index.rst:60: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/tmp/tmpiodbjbom/d819d1f3d0bed977cdfa926fb309a76a8e394462/docs/autoapi/topostats/tracing/tracingfuncs/index.rst:215: WARNING: Block quote ends without a blank line; unexpected unindent.
/tmp/tmpiodbjbom/d819d1f3d0bed977cdfa926fb309a76a8e394462/docs/data_dictionary.md:1: WARNING: Document headings start at H2, not H1 [myst.header]

Extension error (sphinx_autodoc_typehints):
Handler <function process_docstring at 0x7d94184b4860> for event 'autodoc-process-docstring' threw an exception (exception: The frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.)
Traceback (most recent call last):
  File "/home/neil/.virtualenvs/topostats/bin/sphinx-multiversion", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/neil/.virtualenvs/topostats/lib/python3.12/site-packages/sphinx_multiversion/main.py", line 338, in main
    subprocess.check_call(cmd, cwd=current_cwd)
  File "/usr/lib/python3.12/subprocess.py", line 413, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '('/home/neil/.virtualenvs/topostats/bin/python', '-R', '-m', 'sphinx', '-D', 'smv_metadata_path=/tmp/tmpiodbjbom/versions.json', '-D', 'smv_current_version=v2.0.0', '-c', '/home/neil/work/git/hub/AFM-SPM/TopoStats/docs', '/tmp/tmpiodbjbom/d819d1f3d0bed977cdfa926fb309a76a8e394462/docs', '/home/neil/work/git/hub/AFM-SPM/TopoStats/docs/_build/v2.0.0')' returned non-zero exit status 2.

It looks similar to #450 and I think it might be fix-able by updating src/sphinx_autodoc_typehints/__init__.py and importing and using argparse.ArgumentParser instead as indicated, but haven't been able to reconcile docutils.frontend.OptionParser class with argparse.ArgumentParser.

[webknjaz]

Just hit this one too. docutils v0.21.2. It wasn't obvious what triggers it, since it worked in one project but failed in a very similar one.
Reading through https://github.com/tox-dev/sphinx-autodoc-typehints/blob/ffea355/src/sphinx_autodoc_typehints/__init__.py#L840-L848, I now realize that this only happens when there's docstrings having neither :return(s):, nor :rtype: in them.

So an immediate workaround is to add a :returns: entry, it seems. I'll get back to looking into it once I apply it to my project.

[webknjaz]

The warning was added 2 years ago: docutils/docutils@6548b56#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659. It seems like there was a plan to replace it with a class inheriting ArgumentParser, which hasn't happened, however. And so docutils was released with a deprecation warning but no actual path forward.

@gaborbernat I think that this extension should just suppress the warning. It looks like there's no other way. WDYT?

[webknjaz]

Meanwhile, I've filled out the complaint form at https://sourceforge.net/p/docutils/bugs/496/.

[webknjaz]

The upstream suggested the following:

- from docutils.frontend import OptionParser
+ from docutils.frontend import get_default_settings

- settings = OptionParser(components=(RSTParser,)).get_default_values()
+ settings = get_default_settings(RSTParser)

[webknjaz]

Hopefully, #507 is enough.