On Tue, Mar 5, 2024 at 1:48 PM Peter Kokot <p...@php.net> wrote: > > On Mon, 12 Feb 2024 at 12:13, Ilija Tovilo <tovilo.il...@gmail.com> wrote: > > > > 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 <youkideari...@gmail.com> > > wrote: > > > > > > 2024年2月11日(日) 21:18 Ilija Tovilo <tovilo.il...@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
