README

A simple PHP script for use in command line. This script takes an XML file generated by phpDocumentor and generates a Sphinx-ready API documentation in the output folder.

Prerequisites

git
composer 2.2+
Sphinx
1. Extension sphinx_rtd_theme
2. Domain PHP
phpDocumentor
PHP 7.4+

Note: if your PHP version is different from 8.2, you might need to run composer update.

Composer Installation

First require the package as a dev dependency.

cd /path/to/your/project
composer require --dev tommander/phpsphinx

php vendor/bin/phpsphinx -i"/path/to/structure.xml" -o"/path/to/docs/api"

Manual Installation

First clone the repo and install dependencies.

cd /some/path
git clone https://github.com/tommander/phpsphinx
cd phpsphinx
composer install

php bin/phpsphinx -i"/path/to/structure.xml" -o"/path/to/docs/api"

Use In Existing Projects

First, check that you have all the prerequisites.

git --version
composer --version
php --version
sphinx-build --version
php phpDocumentor.phar --version

Then you can create a folder for the documentation. In the example, it is docs. Create two subfolders, source and build.

In the docs/source subfolder, create a folder named api and a file named conf.py e.g. with this content:

project = 'A Project'
copyright = '2025, Me'
author = 'Me'
release = '0.0.0'
extensions = ['sphinx_rtd_theme', 'sphinxcontrib.phpdomain']
exclude_patterns = []
primary_domain = 'php'
html_theme = 'sphinx_rtd_theme'

Then you can create .rst files and other subfolders in the source directory as needed. That will be the static part of your documentation. Just don't create anything in the folder api; it will contain the automatically generated docs.

Next, create a file named Makefile in the root of your project e.g. with this content:

SPHINXOPTS    ?=
# If your Sphinx installation is not global, prepend "sphinx-build" with the path to it.
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = docs/source
BUILDDIR      = docs/build

# Put it first so that "make" without argument is like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Now you are ready to generate the documentation.

# Run phpDocumentor.
php phpDocumentor.phar -d src --template="xml" -t phpdoc

# Run PhpSphinx.
php bin/phpsphinx --i"phpdoc/structure.xml" -o"docs/source/api"

# Sphinx cleanup.
make clean

# Sphinx build docs in HTML format.
make html

And if all went well, you should have your beautiful documentation in docs/build.

This flow is just an example; there is plenty of room for adjustment of this flow to your needs.

Quality Assurance

It is recommended to run QA check before pushing anything to the repo. For branches "main" and "devel", this check runs automatically on a push/PR anyway.

PHP_CodeSniffer with coding standards PSR-12 and PHP-Compatibility.

psalm for static analysis.

phpunit for unit testing.

composer validate --strict
composer qa

Issues

Please track in GitHub Issues.

Pull Requests

Contributing.

Documentation

All important information is in the main file src/StructureToRst.php.

Executable bin/phpsphinx is a PHP file that should be called via command-line. It just takes two options (-i for input XML file path and -o for output API docs path) and then calls the code in the main file.

Simple unit test tests/StructureToRstTest.php ensures to a certain degree that, for a given XML structure, an expected output is generated.

License

MIT License.

tommander / phpsphinx

Maintainers

Details