Skip to content

Commit 9faba9b

Browse files
authored
docs: executable guides (#5712)
1 parent f5aef10 commit 9faba9b

File tree

78 files changed

+5813
-120
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

78 files changed

+5813
-120
lines changed

.github/workflows/guides.yaml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Guides
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
env:
8+
COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
9+
COVERAGE: '0'
10+
SYMFONY_DEPRECATIONS_HELPER: max[self]=0
11+
12+
jobs:
13+
docs:
14+
name: Test guides
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v3
19+
- name: Setup PHP with pre-release PECL extension
20+
uses: shivammathur/setup-php@v2
21+
with:
22+
php-version: 8.2
23+
tools: pecl, composer
24+
extensions: intl, bcmath, curl, openssl, mbstring, pdo_sqlite
25+
coverage: none
26+
ini-values: memory_limit=-1
27+
- name: Get composer cache directory
28+
id: composercache
29+
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
30+
shell: bash
31+
- name: Global require pdg
32+
run: |
33+
cd $(composer -n config --global home)
34+
echo "{\"repositories\":[{\"type\":\"vcs\",\"url\":\"https://github.com/php-documentation-generator/php-documentation-generator\"}]}" > composer.json
35+
composer global config --no-plugins allow-plugins.symfony/runtime true
36+
composer global require php-documentation-generator/php-documentation-generator:dev-main
37+
- name: Cache dependencies
38+
uses: actions/cache@v3
39+
with:
40+
path: ${{ steps.composercache.outputs.dir }}
41+
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
42+
restore-keys: ${{ runner.os }}-composer-
43+
- name: Install project dependencies
44+
working-directory: docs
45+
run: composer install --no-interaction --no-progress --ansi
46+
- name: Test guides
47+
working-directory: docs
48+
env:
49+
APP_DEBUG: 0
50+
PDG_AUTOLOAD: ${{ github.workspace }}/docs/vendor/autoload.php
51+
KERNEL_CLASS: \ApiPlatform\Playground\Kernel
52+
run: |
53+
for d in guides/*.php; do
54+
rm -f var/data.db
55+
echo "Testing guide $d"
56+
pdg-phpunit $d
57+
code=$?
58+
if [[ $code -ne 0 ]]; then
59+
break
60+
fi
61+
done
62+
exit $code

.php-cs-fixer.dist.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
->exclude([
1717
'src/Core/Bridge/Symfony/Maker/Resources/skeleton',
1818
'tests/Fixtures/app/var',
19+
'docs/guides',
1920
])
2021
->notPath('src/Symfony/Bundle/DependencyInjection/Configuration.php')
2122
->notPath('src/Annotation/ApiFilter.php') // temporary

docs/.gitignore

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
pages/guide/**/*.mdx
2+
pages/reference/**/*.mdx
3+
pages/tutorial/**/*.mdx
4+
pages/core
5+
pages/create-client
6+
pages/deployment
7+
pages/distribution
8+
pages/extra
9+
pages/schema-generator
10+
pages/sidebar.mdx
11+
.next
12+
node_modules
13+
composer.lock
14+
vendor
15+
var

docs/README.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# API Platform documentation
2+
3+
## Guides
4+
5+
A guide is a PHP executable file that will be transformed into documentation. It follows [Diataxis How-To Guides](https://diataxis.fr/how-to-guides/) practice which is a must read before writing a guide.
6+
7+
Guides are transformed to Markdown using [php-documentation-generator](https://github.com/php-documentation-generator/php-documentation-generator) which is merely a version of [docco](https://ashkenas.com/docco/) in PHP adapted to output markdown.
8+
9+
## WASM
10+
11+
Guides are executable in a browser environment and need to be preloaded using:
12+
13+
```
14+
docker run -v $(pwd):/src -v $(pwd)/public/php-wasm:/public -w /public php-wasm python3 /emsdk/upstream/emscripten/tools/file_packager.py php-web.data --preload "/src" --js-output=php-web.data.js --no-node --exclude '*Tests*' '*features*' '*public*' '*/.*'
15+
```
16+
17+
A build of [php-wasm](https://github.com/soyuka/php-wasm) is needed in the `public/php-wasm` directory to try it out.

docs/composer.json

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"name": "api-platform/playground",
3+
"description": "API Platform wasm playground",
4+
"type": "project",
5+
"license": "MIT",
6+
"autoload": {
7+
"psr-4": {
8+
"ApiPlatform\\Playground\\": "src/"
9+
}
10+
},
11+
"authors": [
12+
{
13+
"name": "soyuka",
14+
"email": "[email protected]"
15+
}
16+
],
17+
"require": {
18+
"api-platform/core": "*",
19+
"symfony/expression-language": "6.2.*",
20+
"nelmio/cors-bundle": "^2.2",
21+
"phpstan/phpdoc-parser": "^1.15",
22+
"symfony/framework-bundle": "6.2.*",
23+
"symfony/property-access": "6.2.*",
24+
"symfony/property-info": "6.2.*",
25+
"symfony/runtime": "6.2.*",
26+
"symfony/security-bundle": "6.2.*",
27+
"symfony/serializer": "6.2.*",
28+
"symfony/validator": "6.2.*",
29+
"symfony/yaml": "^6.2",
30+
"doctrine/orm": "^2.14",
31+
"doctrine/doctrine-migrations-bundle": "^3.2",
32+
"doctrine/doctrine-bundle": "^2.9",
33+
"doctrine/doctrine-fixtures-bundle": "^3.4",
34+
"zenstruck/foundry": "^1.31",
35+
"symfony/http-client": "^6.2",
36+
"symfony/browser-kit": "^6.2",
37+
"justinrainbow/json-schema": "^5.2"
38+
},
39+
"repositories": [
40+
{
41+
"type": "path",
42+
"url": "../",
43+
"options": {
44+
"symlink": false
45+
}
46+
}
47+
],
48+
"config": {
49+
"allow-plugins": {
50+
"symfony/runtime": true
51+
}
52+
},
53+
"require-dev": {
54+
"phpunit/phpunit": "^10"
55+
},
56+
"minimum-stability": "dev"
57+
}

docs/config/bundles.php

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the API Platform project.
5+
*
6+
* (c) Kévin Dunglas <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
declare(strict_types=1);
13+
14+
return [
15+
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
16+
// Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
17+
Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
18+
Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
19+
Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
20+
Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true],
21+
ApiPlatform\Symfony\Bundle\ApiPlatformBundle::class => ['all' => true],
22+
Zenstruck\Foundry\ZenstruckFoundryBundle::class => ['all' => true],
23+
];

docs/config/packages/doctrine.yaml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
doctrine:
2+
dbal:
3+
url: 'sqlite:///%kernel.project_dir%/var/data.db'
4+
orm:
5+
auto_generate_proxy_classes: true
6+
naming_strategy: doctrine.orm.naming_strategy.underscore_number_aware
7+
auto_mapping: false
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
doctrine_migrations:
2+
migrations_paths:
3+
# namespace is arbitrary but should be different from App\Migrations
4+
# as migrations classes should NOT be autoloaded
5+
'DoctrineMigrations': '%kernel.project_dir%/migrations'
6+
enable_profiler: false

docs/config/packages/framework.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
when@test:
2+
framework:
3+
test: true

docs/config/preload.php

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the API Platform project.
5+
*
6+
* (c) Kévin Dunglas <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
declare(strict_types=1);
13+
14+
if (file_exists(dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
15+
require dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php';
16+
}

0 commit comments

Comments
 (0)