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.
