Re: [PHP-DEV] Moving `php-src/docs` forward

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