Add API documentation generation with phpDocumentor

[jonathanhefner]

• 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

---

This PR also includes a commit to fix existing doc errors from phpDocumentor.

You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.

[chr-hertel]

Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...

[jonathanhefner]

@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.

[chr-hertel]

Yup, that's exactly what we want to look at - awesome!
Don't have time tonight, but will def come back this, thanks!

[Nyholm]

Thank you.

Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json

(Make those changes in a separate PR if you think we should merge them)

[jonathanhefner]

Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json

Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.

The changes in composer.json are due to "sort-packages": true, which predates this PR:

php-sdk/composer.json

Lines 70 to 75 in 69cd04f

	"config": {
	"sort-packages": true,
	"allow-plugins": {
	"php-http/discovery": false
	}
	}

How would you like me to proceed?

[Nyholm]

Those changes are related.

Oh, okey.

Sorry, I did not know they were required.

How would you like me to proceed?

I need to you rebase your PR so I can merge.

Can you also link similar PRs to other SDKs?

[chr-hertel]

Looks like @jonathanhefner was basically already all over the place - awesome!
I also tried to get some overview - and made some notes.

SDK Repos & their docs:

• typescript-sdk
  • Documentation in subfolder docs/ in Markdown
  • Currently no deployment
  • PR by Jonathan with Typedoc, Jekyll, Github Pages
    Add API documentation with GitHub Pages deployment typescript-sdk#1109
• python-sdk
  • Documentation in subfolder docs/ in Markdown
  • Deployed with MkDocs to Github Pages
  • PR by Jonathan adding Read the docs config for versioning support in addition
    docs: add Read the Docs configuration for versioned documentation python-sdk#1765
• csharp-sdk
  • Documentation in subfolder docs/ in Markdown
  • Deployed with docfx to GitHub Pages
  • Couldn't find anything from @jonathanhefner
• ruby-sdk
  • Docs are mostly in readme, even if docs/ subfolder is present
  • Deployed with YARD to RubyDoc
  • Done by Jonathan in a first PR - GitHub Pages not available tho atm
    Add API documentation with GitHub Pages deployment ruby-sdk#181
• rust-sdk
  • Documentation in subfolder docs/ in Markdown + Readmes per crates rmcp & rmcp-macros
  • Deployed to Docs.rs
  • PR by Jonathan to include README on docs.rs
    docs: show README content on docs.rs rust-sdk#583
• go-sdk
  • Documentation in subfolder docs/ in Markdown
  • Mostly available right with the packages on go.dev
  • PR by Jonathan to bring it to GitHub pages - not available tho atm:
    docs: add GitHub Pages redirect to latest release documentation go-sdk#702
• kotlin-sdk
  • Documentation in Readme, subfolder docs and with samples/examples
  • API docs deployed to GitHub pages
  • Couldn't find anything from Jonathan
• java-sdk
  • Docs with MDX in main MCP docs
  • Deployed with the main docs
  • PRs by Jonathan to bring it to the repo & maven base API docs
    Enable markdown docs java-sdk#728
    fix: Enable javadoc generation for modules with OSGi metadata java-sdk#705
• swift-sdk
  • Documentation in README
  • Couldn't find a deployed version
  • PR by Jonathan for API docs with DocC
    Add Swift Package Index documentation support  swift-sdk#174

That's what I could find ... no guarantee for completeness :D

My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:

1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
3. Package specific documentation, see pkg.go.dev or packagist.org

I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.