[Docutils-develop] [docutils:bugs] #496 OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode

[Sviatoslav S. <web...@us...>]

---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** open
**Labels:** harmful deprecation 
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Wed Nov 20, 2024 10:13 PM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.