php-src docs - Externals

2 months ago by Ilija Tovilo — view source

unread

Hi everyone.

I would like to start an initiative to centralize documentation of the
PHP internals. As mentioned in a recent e-mail, there's a lot of
useful documentation scattered across the internet, like the PHP
internals book, various blogs of contributors, wiki.php.net, to name a
few. Information is currently hard to discover over multiple mediums.
Some of these mediums are also prone to go stale and can't be updated
by internals (e.g. blog posts).

After a brief discussion at the foundation, we think it's best to
incorporate the documentation directly into the php-src repository.
This makes it very easy to discover, contribute to, and allows
updating documentation right alongside its technical changes. To make
browsing the documentation easier, the documentation is built with
Sphinx and published to GitHub Pages.

I've prepared a PR here:
https://github.com/php/php-src/pull/13338
https://iluuu1994.github.io/php-src/ (will be moved to php.github.io
once merged)

Let me know of any thoughts and suggestions you might have.

Ilija

2 months ago by glash.gnome@gmail.com — view source

unread

centralize documentation of the PHP internals
I'm glad to hear that you're planning to centralize the documentation for
PHP internals.

Let me know of any thoughts and suggestions you might have.
I have a preference for devel-docs/ instead of docs/ . This would make the
doc-en repository a PHP subproject.

2 months ago by Ilija Tovilo — view source

unread

Hi Mönôme

centralize documentation of the PHP internals
I'm glad to hear that you're planning to centralize the documentation for PHP internals.

Let me know of any thoughts and suggestions you might have.
I have a preference for devel-docs/ instead of docs/ . This would make the doc-en repository a PHP subproject.

Can you clarify? Do you mean a separate repository called devel-docs?
I don't hear the term "devel" much outside of package managers. The
suggestion was to put it directly in the php-src repository, where
there's not much confusion about its content (precisely the php-src
repository).

Ilija

2 months ago by kevin@dunglas.fr — view source

unread

I strongly support this initiative.

When I started writing SAPI (even though I already had some experience with the PHP code base), I spent a lot of time reading scattered articles on the subject, many of which were incomplete or outdated. Having a centralized place to search and contribute would make things a lot easier.

2 months ago by Ilija Tovilo — view source

unread

Hi Yuya

It seems you accidentally sent your response to me instead of the list.

2024年2月11日(日) 21:18 Ilija Tovilo tovilo.ilija@gmail.com:

Hi everyone.

I would like to start an initiative to centralize documentation of the
PHP internals.
https://github.com/php/php-src/pull/13338
https://iluuu1994.github.io/php-src/ (will be moved to php.github.io
once merged)

Let me know of any thoughts and suggestions you might have.

Hi, Ilija.
Thank you for your great suggestion.

It seems make sense to have a set of documents about the structure of
php-src in php-src.
Easily create pull requests to them.

Although I have to learn reStructuredText, It is not seems major problem.

For some context, I initially planned to go with the mdBook from the
Rust project (https://github.com/rust-lang/mdBook/) as Markdown is a
bit more approachable. After writing the sample zval chapter, I
noticed some pain points in terms of formatting, most significantly
tables. That said, reStructuredText is far from perfect itself.

As mentioned previously, the other reason for choosing Sphinx was that
it is quite extensible.

Ilija

1 month ago by Peter Kokot — view source

unread

Hi Yuya

It seems you accidentally sent your response to me instead of the list.

2024年2月11日(日) 21:18 Ilija Tovilo tovilo.ilija@gmail.com:

Hi everyone.

I would like to start an initiative to centralize documentation of the
PHP internals.
https://github.com/php/php-src/pull/13338
https://iluuu1994.github.io/php-src/ (will be moved to php.github.io
once merged)

Let me know of any thoughts and suggestions you might have.

Hi, Ilija.
Thank you for your great suggestion.

It seems make sense to have a set of documents about the structure of
php-src in php-src.
Easily create pull requests to them.

Although I have to learn reStructuredText, It is not seems major problem.

For some context, I initially planned to go with the mdBook from the
Rust project (https://github.com/rust-lang/mdBook/) as Markdown is a
bit more approachable. After writing the sample zval chapter, I
noticed some pain points in terms of formatting, most significantly
tables. That said, reStructuredText is far from perfect itself.

As mentioned previously, the other reason for choosing Sphinx was that
it is quite extensible.

Ilija

Wouldn't it be simpler and better in the long run to have a separate
Git repository for the PHP language internal documentation? Because
once this will increase in number of files, also php-...tar.gz archive
files will increase and everything will become more complex. It will
also mess the php-src Git log with documentation changes. And the docs
subdirectory in the php-src can be still used for some possible other
files that are needed for the GitHub interface usage. Now we have the
docs-old subdirectory in php-src, which is a bit messy and it might
take a while to migrate all those to RST. It would be also perhaps
smart to sync this initiative with https://github.com/php/php-langspec
somehow or at least to display all of those together in some GH page.

1 month ago by Jakub Zelenka — view source

unread

Hi,

Hi Yuya

It seems you accidentally sent your response to me instead of the list.

On Sun, Feb 11, 2024 at 5:10 PM youkidearitai youkidearitai@gmail.com
wrote:

2024年2月11日(日) 21:18 Ilija Tovilo tovilo.ilija@gmail.com:

Hi everyone.

I would like to start an initiative to centralize documentation of
the
PHP internals.
https://github.com/php/php-src/pull/13338
https://iluuu1994.github.io/php-src/ (will be moved to php.github.io
once merged)

Let me know of any thoughts and suggestions you might have.

Hi, Ilija.
Thank you for your great suggestion.

It seems make sense to have a set of documents about the structure of
php-src in php-src.
Easily create pull requests to them.

Although I have to learn reStructuredText, It is not seems major
problem.

For some context, I initially planned to go with the mdBook from the
Rust project (https://github.com/rust-lang/mdBook/) as Markdown is a
bit more approachable. After writing the sample zval chapter, I
noticed some pain points in terms of formatting, most significantly
tables. That said, reStructuredText is far from perfect itself.

As mentioned previously, the other reason for choosing Sphinx was that
it is quite extensible.

Ilija

Wouldn't it be simpler and better in the long run to have a separate
Git repository for the PHP language internal documentation?

The problem with this is that it gets easily outdated. If it’s in the same
repo, we can ask for updates during PR and have it as part of review.

Because

once this will increase in number of files, also php-...tar.gz archive
files will increase and everything will become more complex.

Are you talking about release tarball that RM creates or git archive
(github) one? If the former, then we can filter the docs out and if latter,
than I’m not sure why we should care?

It will

also mess the php-src Git log with documentation changes.

The way how I see it is that internal docs are part of code or its addition
so I wouldn’t think it can mess up our git logs that are largely irrelevant
anyway.

And the docs

subdirectory in the php-src can be still used for some possible other
files that are needed for the GitHub interface usage. Now we have the
docs-old subdirectory in php-src, which is a bit messy and it might
take a while to migrate all those to RST. It would be also perhaps
smart to sync this initiative with https://github.com/php/php-langspec

Isn’t this dead and hugely outdated?

Cheers

Jakub

1 month ago by Robert Landers — view source

unread

Hi Yuya

It seems you accidentally sent your response to me instead of the list.

2024年2月11日(日) 21:18 Ilija Tovilo tovilo.ilija@gmail.com:

Hi everyone.

I would like to start an initiative to centralize documentation of the
PHP internals.
https://github.com/php/php-src/pull/13338
https://iluuu1994.github.io/php-src/ (will be moved to php.github.io
once merged)

Let me know of any thoughts and suggestions you might have.

Hi, Ilija.
Thank you for your great suggestion.

It seems make sense to have a set of documents about the structure of
php-src in php-src.
Easily create pull requests to them.

Although I have to learn reStructuredText, It is not seems major problem.

For some context, I initially planned to go with the mdBook from the
Rust project (https://github.com/rust-lang/mdBook/) as Markdown is a
bit more approachable. After writing the sample zval chapter, I
noticed some pain points in terms of formatting, most significantly
tables. That said, reStructuredText is far from perfect itself.

As mentioned previously, the other reason for choosing Sphinx was that
it is quite extensible.

Ilija

Wouldn't it be simpler and better in the long run to have a separate
Git repository for the PHP language internal documentation? Because
once this will increase in number of files, also php-...tar.gz archive
files will increase and everything will become more complex. It will
also mess the php-src Git log with documentation changes. And the docs
subdirectory in the php-src can be still used for some possible other
files that are needed for the GitHub interface usage. Now we have the
docs-old subdirectory in php-src, which is a bit messy and it might
take a while to migrate all those to RST. It would be also perhaps
smart to sync this initiative with https://github.com/php/php-langspec
somehow or at least to display all of those together in some GH page.

Personally, the documentation is part of the code it documents,
otherwise, you don't have documentation, you have content that can be
mistaken for documentation.

Robert Landers
Software Engineer
Utrecht NL