Re: [Docutils-develop] time to release 0.22.b1 ?

[Adam T. <aat...@ou...>]

Dear Günter, Engelbert, all,

[Engelbert]
> adam should get a invitaionfrom pypi.

Thank you! I have accepted the invitation. Please could you also add me to the Docutils project on Test PyPI? [1]

[Engelbert]
> maybe we might put out more betas, for users to try before a release, if they are not developers this might help.

I agree.

[Günter]
> Feel free to commit small, non-controversial changes right away
> (bit for bit, so that I can have a look) and discuss the complex and
> ambiguous ones either on this list, in private mail or the project tickets.

I have made a series of commits starting at [r10019] through to [r10048]. The most notable is [r10043], which removes type annotations for ``docutils.nodes.Node``, as I would like more time to research what the ideal type annotations are, and talk to some static typing experts. Other than that, the commits are mainly small clean-ups, test fixes, etc.

[Günter]
> What would be your proposed timeframe? (I will be offline next week.)

I think we could publish a beta/release candidate at any point, but I have no strong views. I'm also not in any hurry to do so.

[Günter]
> We should try to solve the deprecation warnings. There should be a
> documented way forward, if not, report back and well find a solution
> (as a last restort, we'll turn them into pending deprecation warnings).

You can inspect the deprecation warnings on GitHub [2] (expand the "test with pytest" tab). These are::

    DeprecationWarning: Argument "parser_name" will be removed in Docutils 2.0.
      Specify parser name in the "parser" argument.
      reader: Reader[DocTreeInput] = docutils.readers.doctree.Reader(

    DeprecationWarning: The auxiliary function roles.set_classes() is obsoleted by roles.normalize_options() and will be removed in Docutils 1.0
      set_classes(self.options)

The ``set_classes()`` function is somewhat frequently used [3] and the replacement is very new. Perhaps we should delay the deprecation and use a PendingDeprecationWarning? Likewise with the 'parser_name' argument, support for strings in 'parser' is not yet released, and removal is planned for 2.0, so perhaps we should start with a PendingDeprecationWarning?

[Günter]
> Could you also test building a typical Sphinx doctree with the new
> "validate__" parser setting set to True?
> There may be problems with the custom nodes added by Sphinx.
> (The setting was added due to a feature-request by a Sphinx-extension
> developer.)
>
> __ https://docutils.sourceforge.io/docs/user/config.html#validate

I haven't had time to do so yet, but I will try at some point.

Thanks,
Adam

[1] https://test.pypi.org/project/docutils/
[2] https://github.com/sphinx-doc/sphinx/actions/runs/13728707556/job/38401038459
[3] https://github.com/search?q=%2Fdocutils%5C..*set_classes%2F+language%3APython+NOT+is%3Aarchived++NOT+is%3Afork&type=code