Skip to content

Commit 3b6873a

Browse files
jonathanhefnerclaude
jonathanhefner
and
claude
committed
Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target - Generate docs during CI to catch errors before releases - Set up GitHub Pages with Jekyll for hosting generated docs - Add GitHub Actions workflow to deploy docs to GitHub Pages on releases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 96ab017 commit 3b6873a

File tree

8 files changed

+94
-2
lines changed

8 files changed

+94
-2
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
deploy:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout
16+
uses: actions/checkout@v5
17+
18+
- name: Setup PHP
19+
uses: shivammathur/setup-php@v2
20+
with:
21+
php-version: '8.4'
22+
coverage: "none"
23+
24+
- name: Install Composer
25+
uses: "ramsey/composer-install@v3"
26+
27+
- name: Generate API Documentation
28+
run: make docs
29+
30+
- name: Copy API docs into docs directory
31+
run: cp -r build/docs docs/api
32+
33+
- name: Deploy to gh-pages branch
34+
uses: peaceiris/actions-gh-pages@v4
35+
with:
36+
github_token: ${{ secrets.GITHUB_TOKEN }}
37+
publish_dir: ./docs
38+
enable_jekyll: true

‎.github/workflows/pipeline.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,3 +132,6 @@ jobs:
132132

133133
- name: PHPStan
134134
run: vendor/bin/phpstan analyse
135+
136+
- name: Documentation
137+
run: make docs

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,8 @@ examples/**/dev.log
77
examples/**/cache
88
examples/**/sessions
99
results
10+
11+
# phpDocumentor
12+
build/
13+
.phpdoc/
14+
phpDocumentor.phar

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: deps-stable deps-low cs phpstan tests unit-tests inspector-tests coverage ci ci-stable ci-lowest
1+
.PHONY: deps-stable deps-low cs phpstan tests unit-tests inspector-tests coverage ci ci-stable ci-lowest docs
22

33
deps-stable:
44
composer update --prefer-stable
@@ -35,3 +35,8 @@ ci: ci-stable
3535
ci-stable: deps-stable cs phpstan tests
3636

3737
ci-lowest: deps-low cs phpstan tests
38+
39+
docs:
40+
vendor/bin/phpdoc
41+
@grep -q 'No errors have been found' build/docs/reports/errors.html || \
42+
(echo "Documentation errors found. See build/docs/reports/errors.html" && exit 1)

‎composer.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
"nyholm/psr7": "^1.8",
3838
"nyholm/psr7-server": "^1.1",
3939
"php-cs-fixer/shim": "^3.91",
40+
"phpdocumentor/shim": "^3",
4041
"phpstan/phpstan": "^2.1",
4142
"phpunit/phpunit": "^10.5",
4243
"psr/simple-cache": "^2.0 || ^3.0",
@@ -69,7 +70,8 @@
6970
},
7071
"config": {
7172
"allow-plugins": {
72-
"php-http/discovery": false
73+
"php-http/discovery": false,
74+
"phpdocumentor/shim": true
7375
},
7476
"sort-packages": true
7577
}

‎docs/_config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
include:
2+
- _*

‎docs/index.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta http-equiv="refresh" content="0; url=api/">
6+
<link rel="canonical" href="api/">
7+
<title>MCP PHP SDK Documentation</title>
8+
</head>
9+
<body>
10+
<p>Redirecting to <a href="api/">API Documentation</a>...</p>
11+
</body>
12+
</html>

‎phpdoc.dist.xml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<phpdocumentor
3+
configVersion="3"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5+
xmlns="https://www.phpdoc.org"
6+
xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd"
7+
>
8+
<title>MCP PHP SDK</title>
9+
<paths>
10+
<output>build/docs</output>
11+
</paths>
12+
<version number="latest">
13+
<api>
14+
<source dsn=".">
15+
<path>src</path>
16+
</source>
17+
<output>api</output>
18+
<ignore>
19+
<path>vendor/**/*</path>
20+
<path>tests/**/*</path>
21+
</ignore>
22+
</api>
23+
</version>
24+
<setting name="graphs.enabled" value="true"/>
25+
</phpdocumentor>

0 commit comments

Comments
 (0)