refactor: clean up docker cmds and improve code blocks (#2041)

Author: vinceAmstoutz

CONTRIBUTING.md

@@ -24,11 +24,11 @@ By contributing to this project, you agree to abide by our [Code of Conduct](htt
 1. Fork this repository by clicking the "Fork" button at the top right of the `api-platform/docs` repository page.
 
 2. Clone the forked repository to your local machine:
-   ```bash
+   ```console
      git clone https://github.com/your-username/repository-name.git
    ```
 3. Create a new branch for your contribution:
-   ```bash
+   ```console
      git switch -c docs-your-branch-name
    ```
 4. Commit and push your changes

admin/getting-started.md

@@ -58,8 +58,7 @@ nelmio_cors:
 Clear the cache to apply this change:
 
 ```console
-docker compose exec php \
-    bin/console cache:clear --env=prod
+bin/console cache:clear --env=prod
 ```
 
 Your new administration interface is ready! Type `npm start` to try it!

core/file-upload.md

@@ -25,8 +25,7 @@ api_platform:
 Install the bundle with the help of Composer:
 
 ```console
-docker compose exec php \
-    composer require vich/uploader-bundle
+composer require vich/uploader-bundle
 ```
 
 This will create a new configuration file that you will need to slightly change

core/graphql.md

@@ -13,7 +13,7 @@ Once enabled, you have nothing to do: your schema describing your API is automat
 To enable GraphQL and its IDE (GraphiQL and GraphQL Playground) in your API, simply require the `api-platform/graphql` package using Composer:
 
 ```console
-    composer require api-platform/graphql
+composer require api-platform/graphql
 ```
 
 You can now use GraphQL at the endpoint: `https://localhost:8443/graphql`.

core/json-schema.md

@@ -10,15 +10,13 @@ The generated schema can be used with libraries such as [react-json-schema-form]
 To export the schema corresponding to an API Resource, run the following command:
 
 ```console
-docker compose exec php \
-    bin/console api:json-schema:generate 'App\Entity\Book'
+bin/console api:json-schema:generate 'App\Entity\Book'
 ```
 
 To see all options available, try:
 
 ```console
-docker compose exec php \
-    bin/console help api:json-schema:generate
+bin/console help api:json-schema:generate
 ```
 
 ## Overriding the JSON Schema Specification

core/jwt.md

@@ -1,7 +1,10 @@
 # JWT Authentication
 
-> [JSON Web Token (JWT)](https://jwt.io/) is a JSON-based open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) for creating access tokens that assert some number of claims. For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that he/she is logged in as admin.
-> The tokens are signed by the server's key, so the server is able to verify that the token is legitimate. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context.
+> [JSON Web Token (JWT)](https://jwt.io/) is a JSON-based open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) for creating access tokens that assert
+> some number of claims. For example, a server could generate a token that has the claim "logged in as admin" and
+> provide that to a client. The client could then use that token to prove that he/she is logged in as admin.
+> The tokens are signed by the server's key, so the server is able to verify that the token is legitimate. The tokens
+> are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context.
 >
 > ―[Uncyclopedia](https://en.wikipedia.org/wiki/JSON_Web_Token)
 
@@ -14,11 +17,17 @@ API Platform allows to easily add a JWT-based authentication to your API using [
 We begin by installing the bundle:
 
 ```console
-docker compose exec php \
-    composer require lexik/jwt-authentication-bundle
+composer require lexik/jwt-authentication-bundle
 ```
+Then we need to generate the public and private keys used for signing JWT tokens.
 
-Then we need to generate the public and private keys used for signing JWT tokens. If you're using the [API Platform distribution](../symfony/index.md), you may run this from the project's root directory:
+You can generate them by using this command:
+
+```console
+php bin/console lexik:jwt:generate-keypair
+```
+
+Or if you're using the [API Platform distribution with Symfony](../symfony/index.md), you may run this from the project's root directory:
 
 ```console
 docker compose exec php sh -c '
@@ -30,13 +39,18 @@ docker compose exec php sh -c '
 '
 ```
 
-Note that the `setfacl` command relies on the `acl` package. This is installed by default when using the API Platform docker distribution but may need to be installed in your working environment in order to execute the `setfacl` command.
+Note that the `setfacl` command relies on the `acl` package. This is installed by default when using the API Platform
+docker distribution but may need to be installed in your working environment in order to execute the `setfacl` command.
 
-This takes care of keypair creation (including using the correct passphrase to encrypt the private key), and setting the correct permissions on the keys allowing the web server to read them.
+This takes care of keypair creation (including using the correct passphrase to encrypt the private key), and setting the
+correct permissions on the keys allowing the web server to read them.
 
-Since these keys are created by the `root` user from a container, your host user will not be able to read them during the `docker compose build caddy` process. Add the `config/jwt/` folder to the `api/.dockerignore` file so that they are skipped from the result image.
+If you want the keys to be auto generated in `dev` environment, see an example in the
+[docker-entrypoint script of api-platform/demo](https://github.com/api-platform/demo/blob/a03ce4fb1f0e072c126e8104e42a938bb840bffc/api/docker/php/docker-entrypoint.sh#L16-L17).
 
-If you want the keys to be auto generated in `dev` environment, see an example in the [docker-entrypoint script of api-platform/demo](https://github.com/api-platform/demo/blob/master/api/docker/php/docker-entrypoint.sh).
+Since these keys are created by the `root` user from a container, your host user will not be able to read them during
+the `docker compose build caddy` process. Add the `config/jwt/` folder to the `api/.dockerignore` file so that they are
+skipped from the result image.
 
 The keys should not be checked in to the repository (i.e. it's in `api/.gitignore`). However, note that a JWT token could
 only pass signature validation against the same pair of keys it was signed with. This is especially relevant in a production

core/messenger.md

@@ -12,8 +12,7 @@ Many transports are supported to dispatch messages to async consumers, including
 To enable the support of Messenger, install the library:
 
 ```console
-docker compose exec php \
-    composer require messenger
+composer require symfony/messenger
 ```
 
 ## Dispatching a Resource through the Message Bus

core/mongodb.md

@@ -18,7 +18,7 @@ the legacy [mongo](https://secure.php.net/manual/en/book.mongo.php) extension.
 
 If the `mongodb` PHP extension is not installed yet, [install it beforehand](https://secure.php.net/manual/en/mongodb.installation.pecl.php).
 
-If you are using the [API Platform Distribution](../symfony/index.md), modify the `Dockerfile` to add the extension:
+Or if you are using the [API Platform Distribution with Symfony](../symfony/index.md), modify the `Dockerfile` to add the extension:
 
 ```diff
 # api/Dockerfile
@@ -64,12 +64,11 @@ services:
 # ...
 ```
 
-Once the extension is installed, to enable the MongoDB support, require the [Doctrine MongoDB ODM bundle](https://github.com/doctrine/DoctrineMongoDBBundle)
+In all cases, enable the MongoDB support by requiring the [Doctrine MongoDB ODM bundle](https://github.com/doctrine/DoctrineMongoDBBundle)
 package using Composer:
 
 ```console
-docker compose exec php \
-    composer require doctrine/mongodb-odm-bundle
+composer require doctrine/mongodb-odm-bundle
 ```
 
 Execute the contrib recipe to have it already configured.

core/openapi.md

@@ -20,36 +20,31 @@ You can also dump an OpenAPI specification for your API.
 OpenAPI, JSON format:
 
 ```console
-docker compose exec php \
-    bin/console api:openapi:export
+bin/console api:openapi:export
 ```
 
 OpenAPI, YAML format:
 
 ```console
-docker compose exec php \
-    bin/console api:openapi:export --yaml
+bin/console api:openapi:export --yaml
 ```
 
 Create a file containing the specification:
 
 ```console
-docker compose exec php \
-    bin/console api:openapi:export --output=swagger_docs.json
+bin/console api:openapi:export --output=swagger_docs.json
 ```
 
 If you want to use the old OpenAPI v2 (Swagger) JSON format, use:
 
 ```console
-docker compose exec php \
-    bin/console api:swagger:export
+bin/console api:swagger:export
 ```
 
 It is also possible to use OpenAPI v3.0.0 format:
 
 ```console
-docker compose exec php \
-    bin/console api:openapi:export --spec-version=3.0.0
+bin/console api:openapi:export --spec-version=3.0.0
 ```
 
 ## Overriding the OpenAPI Specification

core/testing.md

@@ -17,8 +17,7 @@ Reuse them to run, for instance, SQL queries or requests to external APIs direct
 Install the `symfony/http-client` and `symfony/browser-kit` packages to enabled the API Platform test client:
 
 ```console
-docker compose exec php \
-    composer require symfony/browser-kit symfony/http-client
+composer require symfony/browser-kit symfony/http-client
 ```
 
 To use the testing client, your test class must extend the `ApiTestCase` class:

create-client/nextjs.md

@@ -15,33 +15,42 @@ If you use API Platform, jump to the next section!
 
 Alternatively, create a Next.js application by executing:
 
-```console
-# using pnpm (recommended)
-pnpm create next-app --typescript
-# or using npm
-npm init next-app --typescript
-# or using yarn
-yarn create next-app --typescript
-```
+- Pnpm (recommended)
+    ```console
+    pnpm create next-app --typescript
+    ```
+- Npm
+    ```console
+    npm init next-app --typescript
+    ```
+- Yarn
+    ```console
+    yarn reate next-app --typescript
+    ```
+
 
 Install the required dependencies:
 
-```console
-# using pnpm
-pnpm install isomorphic-unfetch formik react-query
-# or using npm
-npm install isomorphic-unfetch formik react-query
-# or using yarn
-yarn add isomorphic-unfetch formik react-query
-```
+- Pnpm (recommended)
+    ```console
+    pnpm install isomorphic-unfetch formik react-query
+    ```
+- Npm
+    ```console
+    npm install isomorphic-unfetch formik react-query
+    ```
+- Yarn
+    ```console
+    yarn add isomorphic-unfetch formik react-query
+    ```
 
 The generated HTML will contain [Tailwind CSS](https://tailwindcss.com) classes.
 Optionally, [follow the Tailwind installation guide for Next.js projects](https://tailwindcss.com/docs/guides/nextjs)
 (Tailwind is preinstalled in [the API Platform Symfony variant](../symfony/index.md))
 
 ## Generating Routes
 
-If you use the API Platform symfony variant, generating all the code you need for a given resource is as simple as running the following command:
+If you are using the [API Platform Distribution with Symfony](../symfony/index.md) generating all the code you need for a given resource is as simple as running the following command:
 
 ```console
 docker compose exec pwa \
@@ -50,16 +59,20 @@ docker compose exec pwa \
 
 Omit the resource flag to generate files for all resource types exposed by the API.
 
-If you don't use the standalone installation, run the following command instead:
-
-```console
-# using pnpm
-pnpm create @api-platform/client https://demo.api-platform.com . --generator next --resource book
-# or using npm
-npm init @api-platform/client https://demo.api-platform.com . -- --generator next --resource book
-# or using yarn
-yarn create @api-platform/client https://demo.api-platform.com . --generator next --resource book
-```
+Or if you don't use the standalone installation, run the following command instead:
+
+- Pnpm (recommended)
+    ```console
+    pnpm create @api-platform/client https://demo.api-platform.com . --generator next --resource book
+    ```
+- Npm
+    ```console
+    npm init @api-platform/client https://demo.api-platform.com . -- --generator next --resource book
+    ```
+- Yarn
+    ```console
+    yarn create @api-platform/client https://demo.api-platform.com . --generator next --resource book
+    ```
 
 Replace the URL by the entrypoint of your Hydra-enabled API.
 You can also use an OpenAPI documentation with `-f openapi3`.
@@ -85,22 +98,26 @@ export default App;
 
 ## Starting the Project
 
-You can launch the server with
-
-```console
-# using pnpm
-pnpm dev
-# or using npm
-npm run dev
-# or using yarn
-yarn dev
-```
-
+You can launch the server with:
+
+- Pnpm (recommended)
+    ```console
+    pnpm dev
+    ```
+- Npm
+    ```console
+    npm run dev
+    ```
+- Yarn
+    ```console
+    yarn dev
+    ```
+  
 Go to `http://localhost:3000/books/` to start using your app.
 
 ## Generating a production build locally with docker compose
 
-If you want to generate a production build locally with docker compose, follow [these instructions](../deployment/docker-compose.md)
+If you want to generate a production build locally with docker compose, follow [these instructions](../deployment/docker-compose.md).
 
 ## Screenshots
 

deployment/docker-compose.md

@@ -89,7 +89,7 @@ Go to `https://your-domain-name.example.com` and enjoy!
 
 Alternatively, if you don't want to expose an HTTPS server but only an HTTP one, run the following command:
 
-```bash
+```console
 SERVER_NAME=http://localhost \
 MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
 TRUSTED_HOSTS='^localhost|php$' \
@@ -142,7 +142,7 @@ pwa:
 
 Begin by starting the php service container:
 
-```bash
+```console
 SERVER_NAME=http://localhost \
 MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
 TRUSTED_HOSTS='^localhost|php$' \
@@ -162,13 +162,13 @@ NEXT_PUBLIC_ENTRYPOINT=http://php
 
 #### 4. Build the pwa service
 
-```bash
+```console
 docker compose -f compose.yaml -f compose.prod.yaml build pwa
 ```
 
 #### 5. Finally, bring up the full project
 
-```bash
+```console
 SERVER_NAME=http://localhost \
 MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
 TRUSTED_HOSTS='^localhost|php$' \