Re: Consolidating/normalizing the PHP documentation build instructions

On Thu, Oct 3, 2024, at 11:36 AM, Jim Winstead wrote:
> Hi,
> 
> This has come up in a couple of GitHub issues lately, such as this comment:
> 
> https://github.com/php/doc-en/issues/3240#issuecomment-2391486860
> 
> The documentation and tools for building the PHP documentation are a little scattered at the moment, and I think it would be good to pull them together into one place. The instructions are scattered between `doc-en/README.md`, `doc-base/README.md`, `docs-base/CONTRIBUTING_DOCS.md` and on http://doc.php.net. Not all of the translations have a `README.md`, and just from looking at those that do, they may not necessarily reflect a standard/current practice for building the docs.
> 
> What I'd like to do is pull everything together in the `doc-base` repository in a `docs` directory, and we can update doc.php.net to use those files instead of what currently lives in the tutorial directory in `web-docs`. Each language repository will then get a README.md pointing to those instructions (and language-specific notes can be added as necessary).
> 
> This puts the documentation about building the documentation into repos that the docs team has responsibility for, and leaves the web side of it to a repo under the web team's responsibility.
> 
> Any objections or other thoughts on cleaning this up?

Here's a first draft of what pulling all of the docs into the `doc-base` repo could look like:

https://github.com/jimwins/doc-base/blob/clean-up-phpdoc-docs/docs/README.md

Draft PR: https://github.com/php/doc-base/pull/159

Jim