Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:122565
Precedence: bulk
MIME-Version: 1.0
References: <CAPyj-LCnOYmMv4b0bxGaHsS-0j8ptjTt95f48Zt_JUQh6NB_8g@mail.gmail.com>
 <CAEPPVa0rUkgajvApdiA+KVQMKALnG2cFTCPisanKSx1hbc6h=A@mail.gmail.com> <CAPyj-LAeaiv64_7Y_RUsRf9wHOdbfAYqtUvr-Qu36OrN_OKjxQ@mail.gmail.com>
In-Reply-To: <CAPyj-LAeaiv64_7Y_RUsRf9wHOdbfAYqtUvr-Qu36OrN_OKjxQ@mail.gmail.com>
Date: Tue, 5 Mar 2024 13:45:39 +0100
Message-ID: <CAAfnsFX0Nb8u9OMHQUyVyD_ZA31_E1_CCQgGyPzp7uGZr6qBog@mail.gmail.com>
Subject: Re: [PHP-DEV] php-src docs
To: Ilija Tovilo <tovilo.ilija@gmail.com>
Cc: PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
From: petk@php.net (Peter Kokot)

On Mon, 12 Feb 2024 at 12:13, Ilija Tovilo <tovilo.ilija@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=E2=80=AFPM youkidearitai <youkidearitai@gmai=
l.com> wrote:
> >
> > 2024=E5=B9=B42=E6=9C=8811=E6=97=A5(=E6=97=A5) 21:18 Ilija Tovilo <tovil=
o.ilija@gmail.com>:
> > >
> > > Hi everyone.
> > >
> > > I would like to start an initiative to centralize documentation of th=
e
> > > 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 proble=
m.
>
> 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.