php-src docs

php.internals

Ilija Tovilo

2 years ago
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

Glash Gnome

2 years ago
> 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.

Ilija Tovilo

2 years ago
Hi Mönôme On Sun, Feb 11, 2024 at 2:20 PM Mönôme Epson <glash.gnome@gmail.com> wrote:
> > > 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

Kévin Dunglas

2 years ago
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.