Hi, On Tue, 5 Mar 2024 at 12:48, 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? 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
