Sphinx-4.0.0b1 released

[Komiya Takeshi]

Hi all,

We just released Sphinx-4.0.0b1.
It has many changes including incompatible ones.
Please confirm it working fine on your documents.

In detail, please see CHANGES:
https://github.com/sphinx-doc/sphinx/blob/4.0.x/CHANGES

You can use it with: pip install --pre Sphinx

Since this is a beta release, we expect that you may encounter bugs.
If you find a bug, please file an issue on Github issues:
https://github.com/sphinx-doc/sphinx/issues

Thanks,
Takeshi KOMIYA

[Guenter Milde]

Hi Komiya-san,

On 2021-04-11, Komiya Takeshi wrote:

> We just released Sphinx-4.0.0b1.
> It has many changes including incompatible ones.
> Please confirm it working fine on your documents.

Please consider to test the upcoming 17.1 Docutils release
and (if it passes) allow "docutils < 0.18" compatiblitily
before doing the final 4.0 release.

Günter

[Guenter Milde]

Update.

Reading about the HTML5 writer problems, I wonder whether it would be better
to keep Sphinx bound to Docutils 0.16 until the second part of the transfer
to semantic tags is done. (See Future Changes in the `release notes`__).

__ https://repo.or.cz/docutils.git/blob_plain/HEAD:/docutils/RELEASE-NOTES.txt


Another idea is to move the HTML5 output changes to a new html5 writer,
and keep "html5_polyglot" in 0.16-state for backwards compatiblitiy.

Thanks,
Günter

[Komiya Takeshi]

Hi Günter,

Thank you for your support. Personally, I'd like to upgrade to the
latest version ASAP. But, we're discussing with the RTD team about the
rule of pinning and unpinning the docutils dependency. So please wait
a moment.

>Another idea is to move the HTML5 output changes to a new html5 writer,
and keep "html5_polyglot" in 0.16-state for backwards compatiblitiy.

I think it's not a better way. It brings complexity to the
docutils-core. And I believe Sphinx should not stop the improvement of
docutils itself. So it would be better to create another original HTML
writer if we really need to support old HTML tags (IMO, it's not a
good way).

Thanks,
Takeshi KOMIYA

2021年4月12日(月) 17:57 Guenter Milde <mi...@users.sf.net>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/s5120e%24fqi%241%40ciao.gmane.io.

[Guenter Milde]

Hi Komiya-san,

Thank you for the fast reply.

On 2021-04-12, Komiya Takeshi wrote:

> Thank you for your support. Personally, I'd like to upgrade to the
> latest version ASAP. But, we're discussing with the RTD team about the
> rule of pinning and unpinning the docutils dependency. So please wait
> a moment.

Glad to hear this.

After reading the various issues (#9056, #9088, #9091 and related), I
come back to the former idea:

I suggest to keep the pin at "docutils < 0.17" in Sphinx 3.x but

raise the pin to "docutils < 0.18" in Sphinx 4.0

after the 0.17.1 bug-fix is avaibable on pypi (should be this week).


Rationale:

We became aware of 3 problems with Docutils 0.17:

a) Encoding error with LC_ALL=C when importing the "latex2e" writer,
https://sourceforge.net/p/docutils/bugs/415/

b) problem with the new "line_length_limit" configuration setting when
using the Docutils "rst" parser,
https://sourceforge.net/p/docutils/bugs/415/

c) changed HTML5 output breaks custom CSS (not reported to Docutils).


The first two problems are fixed in 0.17.1.

The remaining problem (changed HTML5 output) should not prevent using 0.17.1
with Sphinx 4.x:

* As 4.0.0 is a major release, API-breaking changes are "allowed".
(We don't even need to decide whether changed HTML output is in fact an
API change.)

* The HTML5 output changes with Docutils 0.17.x can be documented as
one of the many CHANGES between Sphinx versions 3 and 4, e.g.

Sphinx now supports Docutils 0.12 to 0.17. Watch for changes in
HTML5 output with version 0.17.

This should help downstream projects depending on Sphinx but no direct
dependency on Docutils: they need to test for breaks with 4.0 anyway,
pining "Sphinx < 4 (and the pin on Docutils < 0.17 in Sphinx 3) avoids
surprises.

IMO, raising the Docutils dependency limit may even be worth a small delay
and possibly second pre-release to allow more downstram testing before
releasing Sphinx 4.0, but this is up to the Sphinx community.


The next Docutils "feature release" (0.18 or 1.0) will include the
`second part of the transfer to semantic tags`.
https://repo.or.cz/docutils.git/blob_plain/HEAD:/docutils/RELEASE-NOTES.txt
Whether it will be "cleared" in Sphinx 4.x or Sphinx 5.0 can be decided
later.


Thanks,
Günter

[Komiya Takeshi]

Hi all,

We just released Sphinx-4.0.0b2.

2021年4月12日(月) 0:40 Komiya Takeshi <i.tk...@gmail.com>:

[Guenter Milde]

Dear Komiya-san,

On 2021-04-29, Komiya Takeshi wrote:

> We just released Sphinx-4.0.0b2.
> It has many changes including incompatible ones.
> Please confirm it working fine on your documents.

Thank you for the release and sorry for the confusion around Docutils
version pinning.

Günter

[Komiya Takeshi]

>Thank you for the release and sorry for the confusion around Docutils
>version pinning.

Don't mind. I don't mind it.
Indeed, discussion around the version pinning is a bit annoying to me.
But it's important to keep the quality of Sphinx better.

Let's getting both Sphinx and docutils better :-)

Takeshi KOMIYA

2021年4月30日(金) 16:34 Guenter Milde <mi...@users.sf.net>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.

> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/s6gbtb%24h2v%241%40ciao.gmane.io.