Skip to content

Commit 940eb90

Browse files
jonathanhefnerclaudechr-hertel
authored
Add API documentation generation with phpDocumentor (#184)
* 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> * Fix phpDocumentor errors in type annotations Change class-string union types to use phpDocumentor-compatible syntax and reorder docblock tags so class descriptions precede `@author` tags. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix CI: pin phar-io/composer-distributor ^1.0.2 phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong package version when determining the phpDocumentor download URL, causing CI to fail with 404 errors when using --prefer-lowest. Version 1.0.2 fixes this issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Integrate markdown guides into phpDocumentor output Configure phpDocumentor to generate both API documentation and user guides in a single unified site. This replaces the previous Jekyll-based approach where API docs were copied into the docs folder. - Add `<guide>` configuration to `phpdoc.dist.xml` - Create custom template with "Guides" navigation link - Replace `docs/index.html` redirect with `docs/index.md` guide index - Update workflow to publish `build/docs` directly without Jekyll - Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fine-tuning for path, config, and layout --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
1 parent 2fe9825 commit 940eb90

File tree

12 files changed

+131
-7
lines changed

12 files changed

+131
-7
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
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 Documentation
28+
run: make docs
29+
30+
- name: Deploy to gh-pages branch
31+
uses: peaceiris/actions-gh-pages@v4
32+
with:
33+
github_token: ${{ secrets.GITHUB_TOKEN }}
34+
publish_dir: ./.phpdoc/build
35+
enable_jekyll: false

‎.github/workflows/pipeline.yaml‎

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

143143
- name: PHPStan
144144
run: vendor/bin/phpstan analyse
145+
146+
- name: Documentation
147+
run: make docs

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,7 @@ examples/**/sessions
99
tests/Conformance/results
1010
tests/Conformance/sessions
1111
tests/Conformance/logs/*.log
12+
13+
# phpDocumentor
14+
.phpdoc/build/
15+
.phpdoc/cache/

‎.phpdoc/template/base.html.twig‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{% extends 'layout.html.twig' %}
2+
3+
{% set topMenu = {
4+
"menu": [
5+
{ "name": "Guides", "url": "docs/index.html"},
6+
{ "name": "Specification", "url": "https://modelcontextprotocol.io/" }
7+
],
8+
"social": [
9+
{ "iconClass": "fab fa-github", "url": "https://github.com/modelcontextprotocol/php-sdk"},
10+
{ "iconClass": "fab fa-discord", "url": "https://discord.gg/6CSzBmMkjX"}
11+
]
12+
}
13+
%}

‎.phpdoc/template/components/header-title.html.twig‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<h1 class="phpdocumentor-title">
2+
<a href="{{ path('/docs/index.html') }}" class="phpdocumentor-title__link">
3+
<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 195 195" fill="none">
4+
<path d="M25 97.8528L92.8823 29.9706C102.255 20.598 117.451 20.598 126.823 29.9706V29.9706C136.196 39.3431 136.196 54.5391 126.823 63.9117L75.5581 115.177" stroke="black" stroke-width="12" stroke-linecap="round"/>
5+
<path d="M76.2653 114.47L126.823 63.9117C136.196 54.5391 151.392 54.5391 160.765 63.9117L161.118 64.2652C170.491 73.6378 170.491 88.8338 161.118 98.2063L99.7248 159.6C96.6006 162.724 96.6006 167.789 99.7248 170.913L112.331 183.52" stroke="black" stroke-width="12" stroke-linecap="round"/>
6+
<path d="M109.853 46.9411L59.6482 97.1457C50.2757 106.518 50.2757 121.714 59.6482 131.087V131.087C69.0208 140.459 84.2168 140.459 93.5894 131.087L143.794 80.8822" stroke="black" stroke-width="12" stroke-linecap="round"/>
7+
</svg>
8+
<span style="margin-left: 0.25em;">{{ project.name }}</span>
9+
</a>
10+
</h1>

‎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 conformance-tests
1+
.PHONY: deps-stable deps-low cs phpstan tests unit-tests inspector-tests coverage ci ci-stable ci-lowest conformance-tests docs
22

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

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

‎composer.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,9 @@
3636
"laminas/laminas-httphandlerrunner": "^2.12",
3737
"nyholm/psr7": "^1.8",
3838
"nyholm/psr7-server": "^1.1",
39+
"phar-io/composer-distributor": "^1.0.2",
3940
"php-cs-fixer/shim": "^3.91",
41+
"phpdocumentor/shim": "^3",
4042
"phpstan/phpstan": "^2.1",
4143
"phpunit/phpunit": "^10.5",
4244
"psr/simple-cache": "^2.0 || ^3.0",
@@ -69,7 +71,8 @@
6971
},
7072
"config": {
7173
"allow-plugins": {
72-
"php-http/discovery": false
74+
"php-http/discovery": false,
75+
"phpdocumentor/shim": true
7376
},
7477
"sort-packages": true
7578
}

‎docs/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# MCP PHP SDK Guides
2+
3+
- [MCP Elements](mcp-elements.md) — Core capabilities (Tools, Resources, Resource Templates, and Prompts) with registration methods.
4+
- [Server Builder](server-builder.md) — Fluent builder class for creating and configuring MCP server instances.
5+
- [Transports](transports.md) — STDIO and HTTP transport implementations with guidance on choosing between them.
6+
- [Server-Client Communication](server-client-communication.md) — Methods for servers to communicate back to clients: sampling, logging, progress, and notifications.
7+
- [Examples](examples.md) — Example projects demonstrating attribute-based discovery, dependency injection, HTTP transport, and more.

docs/client-communication.md renamed to docs/server-client-communication.md

File renamed without changes.

‎phpdoc.dist.xml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
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>.phpdoc/build</output>
11+
</paths>
12+
<version number="latest">
13+
<folder>latest</folder>
14+
<api ignore-packages="true">
15+
<source dsn=".">
16+
<path>src</path>
17+
</source>
18+
<output>api</output>
19+
<ignore>
20+
<path>vendor/**/*</path>
21+
<path>tests/**/*</path>
22+
</ignore>
23+
<ignore-tags>
24+
<ignore-tag>phpstan-type</ignore-tag>
25+
<ignore-tag>phpstan-type-import</ignore-tag>
26+
<ignore-tag>template</ignore-tag>
27+
<ignore-tag>template-covariant</ignore-tag>
28+
<ignore-tag>template-extends</ignore-tag>
29+
<ignore-tag>template-implements</ignore-tag>
30+
<ignore-tag>extends</ignore-tag>
31+
<ignore-tag>implements</ignore-tag>
32+
</ignore-tags>
33+
</api>
34+
<guide format="md">
35+
<source dsn=".">
36+
<path>docs</path>
37+
</source>
38+
<output>/</output>
39+
</guide>
40+
</version>
41+
<setting name="guides.enabled" value="true"/>
42+
<setting name="graphs.enabled" value="false"/>
43+
<setting name="template.color" value="black"/>
44+
</phpdocumentor>

0 commit comments

Comments
 (0)