On 21/08/2026 12:26 am, Ilija Tovilo wrote:
None of this is wrong, but I don't think the docs have stalled because
the syntax is too hard. Rather, more time should be designated to them.
It's just hard in today's climate, e.g. LLM security reports have taken
over a large chunk of our time, and even before that issues and user
docs seem more pressing.
The auto-formatter was also removed in your PR (there might not be one
for MyST?), I think that's worth mentioning.
Ilija
I agree with Ilija. While my personal preference would be Markdown, I
don't see much benefit of rewriting/converting the docs to another
markup language. It's not hard to understand RST, nor I have a feeling
it's overcomplicated.
Besides the docs folder, RST is also currently used for UPGRADING,
UPGRADING.INTERNALS and NEWS. Changing these files to another format
will break things as they depend on that specific format (e.g
https://github.com/php/web-php/blob/master/bin/news2html internally, but
external sites parse these files as well).
So given that it does make sense that the docs are also written in the
same format for consistency. Not ignoring the fact that there are MD
files as well.
--
Regards,
Jordi Kroon
