Skip to content

Add dev build tool for PHP manual across different manuals - #337

Open
jordikroon wants to merge 1 commit into
php:masterfrom
jordikroon:dev-build-system
Open

Add dev build tool for PHP manual across different manuals#337
jordikroon wants to merge 1 commit into
php:masterfrom
jordikroon:dev-build-system

Conversation

@jordikroon

@jordikroon jordikroon commented Aug 7, 2026

Copy link
Copy Markdown
Member

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 dev.php script that is primarily meant for local development. And should provide an all-in-one experience for everyone.

Basically:

php dev.php pull # Fetch changes
# Write docs ... 
php dev.php render xhtml # Build docs
php dev.php cs lint # Run linter
php dev.php cs fix # Run fixer (if linter fails)
php dev.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 dev.php render xhtml --lang=it # Build docs
php dev.php cs lint --lang=it # Run linter
php dev.php cs fix --lang=it  # Run fixer (if linter fails)
php dev.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

./dev.php

Dev build tool for the PHP manual, for every language, with or without
Docker. Missing sibling repositories (en, the translation, and without
Docker also phd/docbook-cs) are cloned automatically on first use.
With Docker, phd and docbook-cs ship inside the image and follow their
upstream heads automatically; a checkout next to doc-base overrides
the image's copy and is only moved by pull.

Usage:
  php dev.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
  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. --enable-xml-details), and to
docbook-cs for cs lint/cs fix (e.g. reference/datetime --wide).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant