Skip to content

Commit ae03f03

Browse files
gjtorikiangjtorikian
authored
feat: Add API docs generation and llms.txt index (#382)
1 parent 8757177 commit ae03f03

6 files changed

Lines changed: 151 additions & 2 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Publish API Docs
2+
on:
3+
push:
4+
tags: ['v*']
5+
workflow_dispatch:
6+
permissions:
7+
contents: read
8+
pages: write
9+
id-token: write
10+
concurrency:
11+
group: pages
12+
cancel-in-progress: false
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
18+
- uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # 2.37.0
19+
with:
20+
php-version: '8.2'
21+
tools: composer
22+
- run: ./script/docs
23+
- uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
24+
- name: Archive site
25+
run: |
26+
tar \
27+
--dereference --hard-dereference \
28+
--directory docs/_site \
29+
-cvf "$RUNNER_TEMP/artifact.tar" \
30+
--exclude=.git \
31+
--exclude=.github \
32+
.
33+
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
34+
with:
35+
name: github-pages
36+
path: ${{ runner.temp }}/artifact.tar
37+
retention-days: 1
38+
if-no-files-found: error
39+
deploy:
40+
needs: build
41+
environment:
42+
name: github-pages
43+
url: ${{ steps.deployment.outputs.page_url }}
44+
runs-on: ubuntu-latest
45+
steps:
46+
- uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
47+
id: deployment

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,9 @@ vendor/
88
.phpunit.result.cache
99

1010
# IDEs
11-
.idea/
11+
.idea/
12+
13+
# API docs
14+
docs/_site/
15+
bin/phpDocumentor.phar
16+
.phpdoc/

‎composer.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@
1818
"require-dev": {
1919
"friendsofphp/php-cs-fixer": "^3.0",
2020
"phpstan/phpstan": "^2.1",
21-
"phpunit/phpunit": "^11.5"
21+
"phpunit/phpunit": "^11.5",
22+
"saggre/phpdocumentor-markdown": "^1.0"
2223
},
2324
"autoload": {
2425
"psr-4": {

‎phpdoc.dist.xml‎

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

‎script/docs‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/bin/sh
2+
set -eu
3+
cd "$(dirname "$0")/.."
4+
PHPDOC_PHAR="bin/phpDocumentor.phar"
5+
if [ ! -f "$PHPDOC_PHAR" ]; then
6+
mkdir -p bin
7+
# Pin a recent stable version; check https://github.com/phpDocumentor/phpDocumentor/releases for latest
8+
curl -fsSL -o "$PHPDOC_PHAR" "https://phpdoc.org/phpDocumentor.phar"
9+
chmod +x "$PHPDOC_PHAR"
10+
fi
11+
rm -rf docs/_site
12+
13+
# Pass 1: HTML output via the default template.
14+
php "$PHPDOC_PHAR" --config phpdoc.dist.xml
15+
16+
# Pass 2: Markdown output alongside HTML for AI agents that want
17+
# parallel `.md` files. Uses the saggre/phpdocumentor-markdown
18+
# community template (require-dev). The markdown files are written
19+
# alongside the HTML in docs/_site/ — same paths, different extensions.
20+
MD_TEMPLATE="vendor/saggre/phpdocumentor-markdown/themes/markdown"
21+
if [ ! -d "$MD_TEMPLATE" ]; then
22+
echo "Markdown template missing. Run 'composer install' first." >&2
23+
exit 1
24+
fi
25+
php "$PHPDOC_PHAR" --config phpdoc.dist.xml --template="$MD_TEMPLATE"
26+
27+
# Pass 3: llms.txt — curated index for AI agents, per llmstxt.org.
28+
# Lists the top-level entry points (Core, Services, Exceptions); the 600+
29+
# generated Resource DTOs are reachable by walking classes/WorkOS/Resource/.
30+
SITE="docs/_site"
31+
{
32+
echo "# WorkOS PHP SDK"
33+
echo
34+
echo "> Official PHP SDK for the WorkOS API: authentication, SSO, Directory Sync, audit logs, and more."
35+
echo
36+
echo "API reference auto-generated from source. Each class has a parallel \`.md\` file alongside its HTML page."
37+
echo
38+
echo "## Core"
39+
echo
40+
find "$SITE/classes/WorkOS" -maxdepth 1 -name "*.md" | sort | while read -r f; do
41+
name=$(basename "$f" .md)
42+
echo "- [$name](${f#$SITE/})"
43+
done
44+
echo
45+
echo "## Services"
46+
echo
47+
find "$SITE/classes/WorkOS/Service" -maxdepth 1 -name "*.md" | sort | while read -r f; do
48+
name=$(basename "$f" .md)
49+
echo "- [$name](${f#$SITE/})"
50+
done
51+
echo
52+
echo "## Exceptions"
53+
echo
54+
find "$SITE/classes/WorkOS/Exception" -maxdepth 1 -name "*.md" | sort | while read -r f; do
55+
name=$(basename "$f" .md)
56+
echo "- [$name](${f#$SITE/})"
57+
done
58+
echo
59+
echo "## Optional"
60+
echo
61+
echo "- [Resource DTOs](classes/WorkOS/Resource/): generated request/response types, one \`.md\` file per class."
62+
} > "$SITE/llms.txt"

‎script/docs-serve‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/sh
2+
set -eu
3+
cd "$(dirname "$0")/.."
4+
if [ ! -d docs/_site ]; then
5+
./script/docs
6+
fi
7+
exec php -S 127.0.0.1:4000 -t docs/_site

0 commit comments

Comments
 (0)