Moving `php-src/docs` forward

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

Hey Ilija,

thank you too for the feedback!

Hi Nick

Thanks for bringing this up on the list.

Just to state my thoughts officially:

Why Markdown:

• not yet another syntax to deal with; we all write Markdown
  reST is pretty popular, so not exactly something esoteric. Sure, I
  would also guess that Markdown is more known, but reST is very hard to
  "learn" either.
• renderable by default everywhere; including GitHub and IDEs

I don't think this holds.

Before:
https://github.com/php/php-src/blob/master/docs/source/core/data-structures/reference-counting.rst

After:
https://github.com/NickSdot/php__php-src/blob/6730bde4ee9ddfe618213441f83af70d49dc347f/docs/source/core/data-structures/reference-counting.rst

The problem here being that this isn't pure reST or Markdown, but
MyST. I'd guess the same goes for IDEs. Switching the names to .md
might look better for a good chunk of the file, but then the reST-like
parts won't render well anymore.

That's only because you picked a commit from a non-final state that
solely exists to keep diffs small; mind the still existing .rst
extension. I would really appreciate if you could please at least once
look at the final PR instead of bit by bit arguing about non-final state.

Here is the real picture...

Before:
https://github.com/php/php-src/blob/master/docs/source/index.rst
After:
https://github.com/NickSdot/php__php-src/blob/docs/restructure-08/docs/source/index.md

Before:
https://github.com/php/php-src/blob/master/docs/source/core/data-structures/reference-counting.rst
After:
https://github.com/NickSdot/php__php-src/blob/docs/restructure-08/docs/source/core/memory-management/reference-counting.md

The only thing that cannot render perfectly are the non-standard tables
you asked for. Yet their contents are still very readable (in fact the
raw format you prefer in code) and still stand out (same as TOC; same in
reST/Markdown), reST renders eg important warnings/notes as plain text,
which is stupid That the Markdown syntax is much less noisy is proven by
the diff. Also, let me quote yourself from an internals message:

That said, reStructuredText is far from perfect itself.

So if you now gonna argue that:

• rendering tables is more important than rendering important (!)
  warnings/notes that by definition should be highlighted
• using the syntax all of use daily is not better in general
• suddenly reST which you called "far from perfect" has to be defended
  at all cost

I will gonna fall off my chair for real.

Could you please address:

• why the demo state of the docs would justify being so picky
• why this is a blocker at all if we will have unavoidable "churn" one
  or the other way because of docs-old
• my point that much of this anyway will be touched/replaced in the
  process of getting things updated

You are literally making any progress impossible by requiring no "churn".

Please allow me this... If we actually want to move things forward,
it would be nice if we would not over-complicate and over-think
everything. Otherwise, things just stagnate and (almost) nothing
happens as we see with this started but never finished initiative.
I don't think "let's not overcomplicate" should be an argument for
"let's not question changes". Asking for good reasons for the
switching from one stack to another seems reasonable.

As mentioned above, I'd really appreciate if you would get the full
picture, as in look at least once at the final PR, before questioning
bit by bit based on non-final state picks. I'd also appreciate if you
would not leave the good reasons I added unaddressed/ignored.

So to boil it down, these are internal docs, almost in the same
"demo" state as when they were introduced, not important C code. They
were introduced 2.5 years ago, yet they still have a big "work in
progress" banner, a bunch of todo's inline, and links to 404's (also
meant as todo's) in it. Plus, the overall activity to improve was
rather moderate. The only actual activity was in release-process.md
-- which is already Markdown, and not touched by my PRs at all.

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.

As I mentioned, understandable that y'all are busy with other things.
That's why I am offering to help out. :)

The auto-formatter was also removed in your PR (there might not be one
for MyST?), I think that's worth mentioning.

Nah, that's not really dropped. It's re-activated in a later branch.
Reason for deactivating temporarily was your smaller diff requirement
for the first PR. I didn't open the last branch PR yet because it is WIP
to handle feedback
(https://github.com/php/php-src/commit/0d4035b98bfd5e5d97c5b515cf6630d685b34545)
without requiring me to rewrite all commits in all branches each time.
And, it is literally mentioned in the very diff you saw the removal in.

Ilija

Cheers
Nick