diff --git a/docs/conf.py b/docs/conf.py index b94929c8..f8256b13 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,7 @@ ] myst_enable_extensions = [ "colon_fence", + "deflist", "substitution" ] myst_heading_anchors = 3 diff --git a/docs/usage/composer.md b/docs/usage/composer.md index b5a81115..54b93d22 100644 --- a/docs/usage/composer.md +++ b/docs/usage/composer.md @@ -12,46 +12,46 @@ * [Composer][1] >= 2.1 * [PHP][2] >= 8.1 -## Basic usage +## Global usage -This project should always be used together with the [`create-project`][3] -Composer command: +For a quick start, the project can be used together with Composer's +built-in [`create-project`][3] command: ```bash -composer create-project cpsit/project-builder +composer create-project cpsit/project-builder --no-dev ``` Replace `` with the actual name of your new project. This will be the folder name where to install and set up your project. -```{seealso} -For more command options, refer to the documentation of the -[`create-project`][3] command. +```{tip} +Add the `-v` (or `--verbose`) command option to get a verbose +output of processing steps. ``` -## Recommended usage +## Project-level usage -We recommend using the command like follows: +The project can also be integrated into an existing project as a Composer +plugin: ```bash -composer create-project cpsit/project-builder \ - --prefer-dist \ - --no-dev \ - +composer require --dev cpsit/project-builder ``` -This implies usage of the following options: +Once installed, an additional Composer command `project:create` is available: -* **`--prefer-dist`** ensures that only distributed files are installed - skipping files that are only relevant for development of this repository -* **`--no-dev`** speeds up the installation process by skipping - dev-requirements (those are only required for development purposes) - -```{tip} -Add the `-v` (or `--verbose`) command option to get a verbose -output of processing steps. +```bash +composer project:create [-f|--force] ``` +The following command parameters are available: + +**`target-directory`** +: Path to a directory where to create the new project + +**`-f`, `--force`** +: Force project creation even if target directory is not empty + [1]: https://getcomposer.org/ [2]: https://www.php.net/ [3]: https://getcomposer.org/doc/03-cli.md#create-project diff --git a/docs/usage/docker.md b/docs/usage/docker.md index 848efa6c..a49c2056 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -25,8 +25,10 @@ where to install and set up your new project. Make sure to always mount the volume to `/app`. ```{note} -In the entrypoint, `composer create-project` is executed. It already -contains all [recommended command options](composer.md#recommended-usage). +In the Docker entrypoint, +[`composer project:create`](composer.md#project-level-usage) is executed. +You can pass all available command parameters as Docker command (except +for `target-directory`, which is explicitly set to `/app` within the container). ``` ## Available image tags