Add dev build tool for PHP manual across different manuals

[jordikroon]

I have been long thinking where this tool fits most. But given the docs from doc.php.net live here, all and everything depends on doc-base this feels most natural.

Currently it's very vague for new contributors how to contribute to the docs.

• It either requires either docker or manual cloning of multiple repositories which
• It requires make, which some developers may have never heard of
• Translations have their own set up building tools
• With the upcoming doc-extensions repository it adds even more complexity
• No way to include a linter

This PR adds a phpdoc.php script that is primarily meant for local development. And should provide an all-in-one experience for everyone.

Basically:

php doc.php pull # Fetch changes# Write docs ... 
php phpdoc.php render xhtml # Build docs
php phpdoc.php cs lint # Run linter
php phpdoc.php cs fix # Run fixer (if linter fails)
php phpdoc.php serve # Test changes# Commit changes

For a language this would require the --lang= parameter

php dev.php pull --lang=it # Fetch changes# Write docs ... 
php phpdoc.php render xhtml --lang=it # Build docs
php phpdoc.php cs lint --lang=it # Run linter
php phpdoc.php cs fix --lang=it # Run fixer (if linter fails)
php phpdoc.php serve --lang=it # Test changes# Commit changes

Planning to introduce this tool in 3 stages (when this is considered ready):

• Stage 1: Through this PR. Use this tool, leave any feedback, share bugs, finetune
• Stage 2: Merge this PR, leave an official deprecation marker for the old tool, and update doc.php.net to encourage the use of the new tool
  Stage 3: Remove the old tool, in favor of the new tool

---

php phpdoc.php

Dev build tool for the PHP manual, for every language, with or without
Docker. Missing sibling repositories (en, the translation, web-doc, and
without Docker also phd/docbook-cs) are cloned automatically on first
use.
Usage:
php phpdoc.php <command> [options] [extra arguments]
Commands:
pull Clone missing sibling repositories and update existing ones
configure Assemble and validate the manual, without rendering
render xhtml configure + render the chunked XHTML manual to <lang>/output
render php configure + render the web (PHP) version to <lang>/output
cs lint Run docbook-cs; extra arguments are passed through (paths, --wide)
cs fix Same as cs lint, with --fix: rewrite violations that have fixers
serve Serve <lang>/output over HTTP
serve web-doc Run a local doc.php.net site from the web-doc checkout
docker build Build the Docker image
docker shell Interactive shell inside the container
Options:
--lang=XX Language to operate on (default: en)
--port=NNNN Port for serve (default: 8080)
--docker Force Docker mode (default: used when available)
--no-docker Force local mode
--yes, -y Clone missing repositories without asking for confirmation
Any other argument after the command is passed through: to configure.php
for configure/render (e.g. --with-partial=book.datetime), and to
docbook-cs for cs lint/cs fix (e.g. reference/datetime --wide).

[alfsb]

The usage commaline is very nice. Only the name seems too generic. Perhaps phpdoc.php or devdoc.php, as suggestions.

[jordikroon]

Some updates since the last push:

• dev.php has been renamed to phpdoc.php as suggested
• serve web-doc command has been added which allows to locally test doc.php.net based on the local repositories.

[jordikroon]

I am planning to merge this next weekend-ish. During the week I will do some more testing in order to spot some edge-cases or missing features. After the merge is done, I will start to prepare for stage 2.

Stage 2: Merge this PR, leave an official deprecation marker for the old tool, and update doc.php.net to encourage the use of the new tool

So if you didn't get a chance to get your hands on this tool, please do and share your thoughts. That said nothing will break (yet) as the old building process will still be in place for a short while. At least for a good month or maybe 2.