From 7356cfed5efeffb3f98f956debdd1bb80e7dedd6 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:00:50 +0200 Subject: [PATCH 01/23] Create readme.md --- docs/readme.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/readme.md diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..079e19e --- /dev/null +++ b/docs/readme.md @@ -0,0 +1 @@ +# Workspace From 25219dced4fcde51c154cda969a9077aa3cdb073 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:07:57 +0200 Subject: [PATCH 02/23] Create _config.yml --- docs/_config.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/_config.yml diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..b11e127 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1 @@ +remote_theme: just-the-docs/just-the-docs From 22344428fd52b810f9729c014d7544a18ec65370 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:17:40 +0200 Subject: [PATCH 03/23] Update _config.yml --- docs/_config.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index b11e127..3d9dad7 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1 +1,10 @@ -remote_theme: just-the-docs/just-the-docs +title: workspace +description: Extendible workspace configurator for Laravel +theme: just-the-docs + +url: https://media-code.github.io/workspace + +aux_links: # remove if you don't want this link to appear on your pages + Template Repository: https://github.com/media-code/workspace + +# remote_theme: just-the-docs/just-the-docs From 105b5ef988e99f3d2b0945ea521f66ec8177393f Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:18:48 +0200 Subject: [PATCH 04/23] Update _config.yml --- docs/_config.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 3d9dad7..7cdc29a 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,10 +1,9 @@ title: workspace description: Extendible workspace configurator for Laravel -theme: just-the-docs +remote_theme: just-the-docs/just-the-docs url: https://media-code.github.io/workspace aux_links: # remove if you don't want this link to appear on your pages Template Repository: https://github.com/media-code/workspace -# remote_theme: just-the-docs/just-the-docs From feb6d2338c7c710e7b555c384c44272b0923ac17 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:20:37 +0200 Subject: [PATCH 05/23] Update _config.yml --- docs/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index 7cdc29a..220d136 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,5 +5,5 @@ remote_theme: just-the-docs/just-the-docs url: https://media-code.github.io/workspace aux_links: # remove if you don't want this link to appear on your pages - Template Repository: https://github.com/media-code/workspace + github: https://github.com/media-code/workspace From 8efb68e8faab54aa7b71e223368b021a5cc1daa9 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:22:34 +0200 Subject: [PATCH 06/23] Update _config.yml --- docs/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index 220d136..6207da5 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,5 +5,5 @@ remote_theme: just-the-docs/just-the-docs url: https://media-code.github.io/workspace aux_links: # remove if you don't want this link to appear on your pages - github: https://github.com/media-code/workspace + Github: https://github.com/media-code/workspace From 8580bbe62d875a50305b499c002fc32acd98cede Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:28:23 +0200 Subject: [PATCH 07/23] wip --- docs/index.md | 17 +++++++++++++++++ docs/readme.md | 1 - 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 docs/index.md delete mode 100644 docs/readme.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5776a03 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,17 @@ +[![codestyle](https://github.com/media-code/workspace/actions/workflows/codestyle.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/codestyle.yml) +[![tests](https://github.com/media-code/workspace/actions/workflows/tests.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/tests.yml) +[![coverage](https://img.shields.io/codecov/c/github/media-code/workspace?token=ON4MTY8C1B&color=45%2C190%2C65)](https://codecov.io/gh/media-code/workspace) + +A extendible workspace configurator for Laravel to effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects. + +## Install Workspace in your project + +```bash +composer require gedachtegoed/workspace --dev +``` + +Then run the install command to set up Workspace's configs in your project: + +```bash +php artisan workspace:install +``` diff --git a/docs/readme.md b/docs/readme.md deleted file mode 100644 index 079e19e..0000000 --- a/docs/readme.md +++ /dev/null @@ -1 +0,0 @@ -# Workspace From 6289f6c5605c7383a6f574250fa113811f547a33 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 22:58:26 +0200 Subject: [PATCH 08/23] wip --- docs/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 5776a03..5bc29a9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ A extendible workspace configurator for Laravel to effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects. -## Install Workspace in your project +## Installation ```bash composer require gedachtegoed/workspace --dev @@ -15,3 +15,8 @@ Then run the install command to set up Workspace's configs in your project: ```bash php artisan workspace:install ``` + +{: .note } +> Workspace ships with a handfull carefully selected Integrations. +> +> If you'd like to roll out your own Portable Workspace to share between projects and teams refer to [this section](media-code/github.io/workspace/portable-workspaces) of the documentation From 5271d88be1eb8ed1157ef6cf4cd3d9a78371f2c4 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 23:05:16 +0200 Subject: [PATCH 09/23] wip --- docs/index.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/index.md b/docs/index.md index 5bc29a9..c645178 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,13 @@ Then run the install command to set up Workspace's configs in your project: php artisan workspace:install ``` + + +{: .note-title } +> My note title +> +> A paragraph with a custom title callout + {: .note } > Workspace ships with a handfull carefully selected Integrations. > From 3c0e39ae50622cd6394910ed648c5dac3d40de8b Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 10 Oct 2023 23:14:39 +0200 Subject: [PATCH 10/23] wip --- docs/_config.yml | 4 ++++ docs/index.md | 7 +------ 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 6207da5..98fcd9d 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -7,3 +7,7 @@ url: https://media-code.github.io/workspace aux_links: # remove if you don't want this link to appear on your pages Github: https://github.com/media-code/workspace +callouts: + note: + title: note + color: purple diff --git a/docs/index.md b/docs/index.md index c645178..7e744d0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,7 @@ [![codestyle](https://github.com/media-code/workspace/actions/workflows/codestyle.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/codestyle.yml) [![tests](https://github.com/media-code/workspace/actions/workflows/tests.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/tests.yml) [![coverage](https://img.shields.io/codecov/c/github/media-code/workspace?token=ON4MTY8C1B&color=45%2C190%2C65)](https://codecov.io/gh/media-code/workspace) +[![core coverage](https://img.shields.io/codecov/c/github/media-code/workspace-core?label=core%20coverage&token=ON4MTY8C1B&color=45%2C190%2C65)](https://codecov.io/gh/media-code/workspace-core) A extendible workspace configurator for Laravel to effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects. @@ -17,12 +18,6 @@ php artisan workspace:install ``` - -{: .note-title } -> My note title -> -> A paragraph with a custom title callout - {: .note } > Workspace ships with a handfull carefully selected Integrations. > From effde71ba8b4bf69d76a15fa3172da900ce17103 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Wed, 11 Oct 2023 11:47:37 +0200 Subject: [PATCH 11/23] update gitignore --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index fbec92b..f613b17 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ -DS_Store +.DS_Store /vendor /skeleton From 9f02a7352917ffecc885bd96420fcb05c7579f37 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Wed, 11 Oct 2023 11:47:59 +0200 Subject: [PATCH 12/23] update docs landing page --- core | 1 + docs/index.md | 35 +++++++++++++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 2 deletions(-) create mode 160000 core diff --git a/core b/core new file mode 160000 index 0000000..26673a1 --- /dev/null +++ b/core @@ -0,0 +1 @@ +Subproject commit 26673a1766f41b48f6628cde9f36d575835c3d12 diff --git a/docs/index.md b/docs/index.md index 7e744d0..d2926fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ A extendible workspace configurator for Laravel to effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects. -## Installation +## Quickstart ```bash composer require gedachtegoed/workspace --dev @@ -17,8 +17,39 @@ Then run the install command to set up Workspace's configs in your project: php artisan workspace:install ``` +This command will install all configured Integrations in [workspace-integrations.php](https://github.com/media-code/workspace/blob/main/config/workspace-integrations.php). These are all configurable by publishing the config file. You may remove or override any implementation with your own on a per-project basis. Read more about overriding Integrations [here](media-code/github.io/workspace/customization/overriding-per-project). {: .note } -> Workspace ships with a handfull carefully selected Integrations. + +> Workspace ships with a handfull carefully crafted Integrations. > > If you'd like to roll out your own Portable Workspace to share between projects and teams refer to [this section](media-code/github.io/workspace/portable-workspaces) of the documentation + +## Updating + +Whenever Integrations change upstream you can easily sync it with your project. + +```bash +php artisan workspace:update +``` + +This command will update Workspace itself (by a minor version only) and update the Integration's _composer_ and _npm_ dependencies before rebuilding all your integration configs. + +Please note that while Workspace's internal Integrations are carefully selected, they are higly opinionated. We do encourage you to write your own _Portable Workspace_. + + + + +## Integrate your IDE + +Workspace uses [Duster](https://github.com/tighten/duster) under the hood to facilitate linting and fixing of your code. But to use it you need to manually trigger the command before you commit your code or let CI handle it for you. To bridge the gap you can integrate you IDE so all _Workspace Integrations_ are seamlessly applied when you type. + +```bash +php artisan workspace:integrate +``` + +You'll be prompted for your editor of choice (`vscode` or `phpstorm`). If your team uses both editors simply select them both. + +This will install some configuration to your `.vscode` or `.idea` directory respectively. + +In case of `vscode` after running the `workspace:integrate` command you'll need to install vscode's recommended extentions. If the prompt doesn't appear; Open the command pallette [CMD + Shift + P] and select 'Show Recommended Extensions' and install them. From ffa3e9fcd2e47894775fc2cd8c773be51ddf1d8c Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:01:00 +0200 Subject: [PATCH 13/23] wip --- docs/.gitignore | 1 + docs/_config.yml | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 docs/.gitignore diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d7e9199 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/.jekyll-cache diff --git a/docs/_config.yml b/docs/_config.yml index 98fcd9d..aece380 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -6,8 +6,10 @@ url: https://media-code.github.io/workspace aux_links: # remove if you don't want this link to appear on your pages Github: https://github.com/media-code/workspace - + callouts: note: title: note color: purple + +markdown: GFM From 139ef74e1b431f6688b404bc57cf824355cd48f0 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:16:15 +0200 Subject: [PATCH 14/23] fix submodule issue --- core | 1 - 1 file changed, 1 deletion(-) delete mode 160000 core diff --git a/core b/core deleted file mode 160000 index 26673a1..0000000 --- a/core +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 26673a1766f41b48f6628cde9f36d575835c3d12 From 575be3727937882b7ebe455b31f8d387ad78f75f Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:18:21 +0200 Subject: [PATCH 15/23] wip --- docs/_config.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index aece380..cba15de 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -11,5 +11,3 @@ callouts: note: title: note color: purple - -markdown: GFM From 77199c67c2d55ed2b600276a7e3c372de734cb99 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:21:53 +0200 Subject: [PATCH 16/23] wip --- docs/core-concepts.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/core-concepts.md diff --git a/docs/core-concepts.md b/docs/core-concepts.md new file mode 100644 index 0000000..4926526 --- /dev/null +++ b/docs/core-concepts.md @@ -0,0 +1,7 @@ +# Core concepts + +## Integrations + +## Commands + +# Foo bar From 75bf31443b2843c6eaa65f31a50ef10b8ce4984c Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:28:21 +0200 Subject: [PATCH 17/23] skaffold out some chapters --- docs/core-concepts.md | 2 -- docs/default-integrations.md | 27 +++++++++++++++++++++++++++ docs/portable-workspaces.md | 1 + 3 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 docs/default-integrations.md create mode 100644 docs/portable-workspaces.md diff --git a/docs/core-concepts.md b/docs/core-concepts.md index 4926526..f8b5b2a 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -3,5 +3,3 @@ ## Integrations ## Commands - -# Foo bar diff --git a/docs/default-integrations.md b/docs/default-integrations.md new file mode 100644 index 0000000..8440eae --- /dev/null +++ b/docs/default-integrations.md @@ -0,0 +1,27 @@ +# Default integrations + +Workspace ships with a handfull of default Integrations. Lorem ipsum dolor sit amet. + +## Duster + +Duster is a core integration (shipped with the core). Duster provides the system we hook in to to run all our linters & fixers via the cli. + +## EditorDefaults + +## PHPCodeSniffer + +## PrettierBlade + +## PHPCSFixer + +## IDEHelper + +## Workflows + +## Larastan + +## Aliases + +## TLint + +## Pint diff --git a/docs/portable-workspaces.md b/docs/portable-workspaces.md new file mode 100644 index 0000000..1cf9b6f --- /dev/null +++ b/docs/portable-workspaces.md @@ -0,0 +1 @@ +# Bring your own setup From 53da1ce40d9b537520b2a393656280aa68a54f95 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:30:24 +0200 Subject: [PATCH 18/23] update page orders --- docs/core-concepts.md | 4 ++++ docs/default-integrations.md | 6 +++++- docs/portable-workspaces.md | 5 +++++ 3 files changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/core-concepts.md b/docs/core-concepts.md index f8b5b2a..86deef7 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -1,3 +1,7 @@ +--- +order: 2 +--- + # Core concepts ## Integrations diff --git a/docs/default-integrations.md b/docs/default-integrations.md index 8440eae..c49fe64 100644 --- a/docs/default-integrations.md +++ b/docs/default-integrations.md @@ -1,4 +1,8 @@ -# Default integrations +--- +order: 3 +--- + +# Integrations Workspace ships with a handfull of default Integrations. Lorem ipsum dolor sit amet. diff --git a/docs/portable-workspaces.md b/docs/portable-workspaces.md index 1cf9b6f..a349722 100644 --- a/docs/portable-workspaces.md +++ b/docs/portable-workspaces.md @@ -1 +1,6 @@ +--- +order: 4 +title: Portable Workspaces +--- + # Bring your own setup From 2b54035e2573cfa50f041b54d094bbda21071cc3 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:36:07 +0200 Subject: [PATCH 19/23] wip --- docs/api-reference.md | 5 +++++ docs/portable-workspaces.md | 18 ++++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 docs/api-reference.md diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..b7bc1dd --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,5 @@ +--- +order: 5 +--- + +# API Reference diff --git a/docs/portable-workspaces.md b/docs/portable-workspaces.md index a349722..a8e3d5e 100644 --- a/docs/portable-workspaces.md +++ b/docs/portable-workspaces.md @@ -4,3 +4,21 @@ title: Portable Workspaces --- # Bring your own setup + +## Getting started + +link to template repository + +## Practical example + +## Commands & contribution points + +### workspace:install + +### workspace:update + +### workspace:integrate + +## Hooking into commands + +Using Laravel prompts inside a hook From e7fed6b0b75478ec433f469acc8597ece76bde4d Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:42:48 +0200 Subject: [PATCH 20/23] wip --- docs/core-concepts.md | 9 --------- docs/default-integrations.md | 2 ++ docs/getting-started.md | 6 ++++++ docs/index.md | 5 +++++ 4 files changed, 13 insertions(+), 9 deletions(-) delete mode 100644 docs/core-concepts.md create mode 100644 docs/getting-started.md diff --git a/docs/core-concepts.md b/docs/core-concepts.md deleted file mode 100644 index 86deef7..0000000 --- a/docs/core-concepts.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -order: 2 ---- - -# Core concepts - -## Integrations - -## Commands diff --git a/docs/default-integrations.md b/docs/default-integrations.md index c49fe64..07daf00 100644 --- a/docs/default-integrations.md +++ b/docs/default-integrations.md @@ -6,6 +6,8 @@ order: 3 Workspace ships with a handfull of default Integrations. Lorem ipsum dolor sit amet. +After running `workspace:install` for the first time you will be greeted lorem ipsum dolor sit amet. + ## Duster Duster is a core integration (shipped with the core). Duster provides the system we hook in to to run all our linters & fixers via the cli. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..c517bea --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,6 @@ +--- +order: 2 +title: Getting started +--- + +What to do with this page diff --git a/docs/index.md b/docs/index.md index d2926fa..57ce993 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,8 @@ +--- +order: 1 +title: Installation +--- + [![codestyle](https://github.com/media-code/workspace/actions/workflows/codestyle.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/codestyle.yml) [![tests](https://github.com/media-code/workspace/actions/workflows/tests.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/tests.yml) [![coverage](https://img.shields.io/codecov/c/github/media-code/workspace?token=ON4MTY8C1B&color=45%2C190%2C65)](https://codecov.io/gh/media-code/workspace) From 3fce37e764aa9ac820566cdcd51222f34d7c4fb4 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:44:33 +0200 Subject: [PATCH 21/23] wip --- docs/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 57ce993..1ed0e95 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,5 @@ --- order: 1 -title: Installation --- [![codestyle](https://github.com/media-code/workspace/actions/workflows/codestyle.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/codestyle.yml) From 754365367a9b88d9398765cde9a49b4f10ad0397 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Sat, 14 Oct 2023 22:46:36 +0200 Subject: [PATCH 22/23] wip --- docs/api-reference.md | 2 +- docs/default-integrations.md | 2 +- docs/getting-started.md | 2 +- docs/index.md | 2 +- docs/portable-workspaces.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api-reference.md b/docs/api-reference.md index b7bc1dd..fb273b2 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -1,5 +1,5 @@ --- -order: 5 +nav_order: 5 --- # API Reference diff --git a/docs/default-integrations.md b/docs/default-integrations.md index 07daf00..ed19c2d 100644 --- a/docs/default-integrations.md +++ b/docs/default-integrations.md @@ -1,5 +1,5 @@ --- -order: 3 +nav_order: 3 --- # Integrations diff --git a/docs/getting-started.md b/docs/getting-started.md index c517bea..5acc480 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,5 +1,5 @@ --- -order: 2 +nav_order: 2 title: Getting started --- diff --git a/docs/index.md b/docs/index.md index 1ed0e95..1d7ff09 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ --- -order: 1 +nav_order: 1 --- [![codestyle](https://github.com/media-code/workspace/actions/workflows/codestyle.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/codestyle.yml) diff --git a/docs/portable-workspaces.md b/docs/portable-workspaces.md index a8e3d5e..6753084 100644 --- a/docs/portable-workspaces.md +++ b/docs/portable-workspaces.md @@ -1,5 +1,5 @@ --- -order: 4 +nav_order: 4 title: Portable Workspaces --- From 1d0b896d651d905e74e09e96fdf8b22062abbd70 Mon Sep 17 00:00:00 2001 From: Willem Leuverink Date: Tue, 17 Oct 2023 15:56:19 +0200 Subject: [PATCH 23/23] wip --- docs/_config.yml | 3 + docs/api-reference.md | 73 ++++++++++++++++++++++ docs/digging-deeper.md | 135 ++++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 6 -- docs/index.md | 9 +-- 5 files changed, 216 insertions(+), 10 deletions(-) create mode 100644 docs/digging-deeper.md delete mode 100644 docs/getting-started.md diff --git a/docs/_config.yml b/docs/_config.yml index cba15de..ce5802c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -11,3 +11,6 @@ callouts: note: title: note color: purple + warning: + title: warning + color: red diff --git a/docs/api-reference.md b/docs/api-reference.md index fb273b2..84abfb4 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -3,3 +3,76 @@ nav_order: 5 --- # API Reference + +When building your own Portable Integrations or overriding Project specific Integrations you have access to the following Fluent Builder methods. The example below showcases all Integration features to your exposal and how you'd structure your Integration class. + +{: .note } + +> Any of the Builder methods accept either single value or an array of values & may be invoked more than once. + +```php +use Gedachtegoed\Workspace\Core\Builder; + +class PrettierBlade extends Builder +{ + public function __invoke() + { + $this + //-------------------------------------------------------------------------- + // Package managers + //-------------------------------------------------------------------------- + ->composerRequireDev(array|string $dependencies) + ->composerRequire(array|string $dependencies) + ->composerUpdate(array|string $dependencies) + ->composerScripts(array|string $scripts) + + ->npmInstallDev(array|string $dependencies) + ->npmInstall(array|string $dependencies) + ->npmUpdate(array|string $dependencies) + + //-------------------------------------------------------------------------- + // Duster + //-------------------------------------------------------------------------- + ->provideDusterLintConfig(array $config) + ->provideDusterFixConfig(array $config) + + //-------------------------------------------------------------------------- + // Configs and workflows + //-------------------------------------------------------------------------- + ->publishesConfigs(array $config) + ->publishesWorkflows(array $config) + + //-------------------------------------------------------------------------- + // Gitignore + //-------------------------------------------------------------------------- + ->addToGitignore(string|array $line) + ->removeFromGitignore(string|array $line) + + //-------------------------------------------------------------------------- + // Visual Studio Code integrations + //-------------------------------------------------------------------------- + ->provideVscodeWorkspaceConfig(string|array $line) + ->provideVscodeRecommendedPlugins(string|array $plugin) + ->provideVscodeAvoidPlugins(string|array $plugin) + + //-------------------------------------------------------------------------- + // PhpStorm integrations + //-------------------------------------------------------------------------- + ->providePhpStormWorkspaceConfig(string|array $line) + ->providePhpStormRequiredPlugins(string|array $plugin) + ->providePhpStormSuggestedPlugins(string|array $plugin) + + //-------------------------------------------------------------------------- + // Lifecycle Hooks + //-------------------------------------------------------------------------- + ->beforeInstall(callable $callback) + ->afterInstall(callable $callback) + + ->beforeUpdate(callable $callback) + ->afterUpdate(callable $callback) + + ->beforeIntegration(callable $callback) + ->afterIntegration(callable $callback) + } +} +``` diff --git a/docs/digging-deeper.md b/docs/digging-deeper.md new file mode 100644 index 0000000..ab801ab --- /dev/null +++ b/docs/digging-deeper.md @@ -0,0 +1,135 @@ +--- +nav_order: 2 +title: Digging deeper +--- + +## Core concepts + +Workspace in it's core is a system to automate setting up integrations in a programmatic manner inside a distributable composer package. + +After Workspace is installed, users may upgrade their local configs by running `workspace:update`. This will update to the latest minor version of Workspace (_or a Portable Workspace you've distributed yourself_), update it's Integrations composer & npm dependencies and finally rebuilds all configuration files before it's published to your project. + +Using this system it is a sinch keeping all your integrations synchronized between different projects & teams. + +The same is true for the `workspace:integrate` command, which will publish files to your projects workspace config directories (.vscode & .idea) for vscode & phpstorm respectively. + +## What do you get? + +1. Fluent API for configuring Integrations +2. Head-ache free system for syncing upstream Integration changes +3. Easy to extend, override or roll out your own _Portable Workspaces_ +4. Manage composer & npm dependencies +5. Publish config files for said Integrations +6. Hook Integrations into [Duster's](https://github.com/tighten/duster) lint & fix contribution points +7. Contribute to composer.json `scripts` section +8. Contributes to your gitignore files (add & remove lines) +9. Contributes CI workflow files (comes with workflows for linting, fixing tests) +10. Contributes Editor defaults so devs can start working with your project immediatly (without configuring vscode for php) +11. Contributes IDE integrations for Visual Studio Code & PhpStorm + +Out of the box, Workspace ships with a handfull default Integrations that vary from setting up editor defaults to installing linters & fixers to setting up IDE Helper & installing composer aliases. You can read about what they do [here](media-code.github.io/workspace/default-integrations). + +## Running Duster + +The default Integrations workspace ships with integrate with [tightenco/duster](https://github.com/tighten/duster). +After running `workspace:install` for the first time you'll see a table in your CLI with all composer aliases: + +| alias | description | +| :---------------- | :------------------------------------------------------------------------------------------------- | +| composer lint | Lints your code with duster and phpstan including any additional linters configured in duster.json | +| composer fix | Fixes your code with duster including any additional fixers configured in duster.json | +| composer analyze | Runs phpstan separately | +| composer baseline | Generate a static analysis baseline | + +{: .note } + +> Duster is a Internal Integration & is always enabled as a way for other Integrations to hook into +> +> If you'd like to change the default script aliases please update or override the [Aliases.php](https://github.com/media-code/workspace/blob/main/src/Integrations/Composer/Aliases.php) implementation + +One important thing to note is that all Duster's default integrations will run regardless if you have a Workspace Integration disabled. If you want to run Duster with a custom set of linters you need to update the composer alias accordingly. + +```json +"lint": 'vendor/bin/duster lint --using="phpstan,tlint,pint"', +``` + +Alternatively you may also forward options to the composer alias by appending `--` before any flags. + +```bash +composer lint -- --dirty --using"pint" +``` + +## Overriding Integrations + +It may be the case that a project specific configuration keeps getting overwritten by running `workspace:update`. In this case you might choose to override the Integration's implementation on a per-project basis. + +First you need to publish the config file by running `php artisan vendor:publish --tag="workspace"` + +This will publish the following file to your config folder: + +```php +return [ + EditorDefaults::class, // .editorconfig, file associations & emmet languages + PHPCodeSniffer::class, + PrettierBlade::class, + PHPCSFixer::class, + IDEHelper::class, // IDE helper & update hooks in composer.json + Workflows::class, + Larastan::class, + Aliases::class, // Installs composer scripts + TLint::class, + Pint::class, +]; +``` + +_Note that Duster is always enabled as a core Integration_ + +Here, you may disable any integration you don't want to use. After you've removed a Integration from the config, this will not contribute any configurations to the `install`, `update`, or `integrate` commands. + +{: .note } + +> If you've previously ran `workspace:install` disabled Integration files won't be deleted on `workspace:update` + +When overriding the config you can take two approaches. + +1. Using your own class based integration +2. Using the Fluent Builder inline + +```php +use Gedachtegoed\Workspace\Integrations\EditorDefaults\EditorDefaults; +use Gedachtegoed\Workspace\Core\Builder; + +use App\Workspace\MyCustomPrettierIntegration; + +return [ + // Ships with Workspace. Can be combined with custom Integrations + EditorDefaults::class, + + // Approach 1: FQCN to your custom Integration + MyCustomPrettierIntegration::class, + + // Approach 2: Inlined Integration using the Builder directly. + // This example swaps Aliases.php for it's own implementation + Builder::make() + ->composerScripts([ + 'lint' => 'vendor/bin/duster lint', + 'fix' => 'vendor/bin/duster fix', + 'analyze' => 'vendor/bin/phpstan analyse', + 'baseline' => 'vendor/bin/phpstan analyse --generate-baseline', + ]) + // Hook into the install command. You have full access to the command & Laravel Prompts + ->afterInstall(function (Command $command) { + note('Workspace installed composer aliases for your convenience'); + + table( + ['Command', 'Description'], + [ + ['composer lint', 'Lints your code with duster and phpstan including any additional linters configured in duster.json'], + ['composer fix', 'Fixes your code with duster including any additional fixers configured in duster.json'], + ['composer analyze', 'Runs phpstan separately'], + ['composer baseline', 'Generate a static analysis baseline'], + ] + ); + }) +]; +``` diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 5acc480..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -nav_order: 2 -title: Getting started ---- - -What to do with this page diff --git a/docs/index.md b/docs/index.md index 1d7ff09..ac3f0e4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,6 @@ --- nav_order: 1 +title: Quickstart --- [![codestyle](https://github.com/media-code/workspace/actions/workflows/codestyle.yml/badge.svg)](https://github.com/media-code/workspace/actions/workflows/codestyle.yml) @@ -7,7 +8,7 @@ nav_order: 1 [![coverage](https://img.shields.io/codecov/c/github/media-code/workspace?token=ON4MTY8C1B&color=45%2C190%2C65)](https://codecov.io/gh/media-code/workspace) [![core coverage](https://img.shields.io/codecov/c/github/media-code/workspace-core?label=core%20coverage&token=ON4MTY8C1B&color=45%2C190%2C65)](https://codecov.io/gh/media-code/workspace-core) -A extendible workspace configurator for Laravel to effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects. +Effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects. ## Quickstart @@ -21,13 +22,13 @@ Then run the install command to set up Workspace's configs in your project: php artisan workspace:install ``` -This command will install all configured Integrations in [workspace-integrations.php](https://github.com/media-code/workspace/blob/main/config/workspace-integrations.php). These are all configurable by publishing the config file. You may remove or override any implementation with your own on a per-project basis. Read more about overriding Integrations [here](media-code/github.io/workspace/customization/overriding-per-project). +This command will install all configured Integrations in [workspace-integrations.php](https://github.com/media-code/workspace/blob/main/config/workspace-integrations.php). These are all configurable by publishing the config file. You may remove or override any implementation with your own on a per-project basis. Read more about overriding Integrations [here](media-code/github.io/workspace/digging-deeper/#overriding-integrations). {: .note } > Workspace ships with a handfull carefully crafted Integrations. > -> If you'd like to roll out your own Portable Workspace to share between projects and teams refer to [this section](media-code/github.io/workspace/portable-workspaces) of the documentation +> If you'd like to roll out your own Portable Workspace to share between projects and teams refer to [this section](media-code.github.io/workspace/portable-workspaces) of the documentation ## Updating @@ -39,7 +40,7 @@ php artisan workspace:update This command will update Workspace itself (by a minor version only) and update the Integration's _composer_ and _npm_ dependencies before rebuilding all your integration configs. -Please note that while Workspace's internal Integrations are carefully selected, they are higly opinionated. We do encourage you to write your own _Portable Workspace_. +_Please note that while Workspace's internal Integrations are carefully selected, they are higly opinionated. We do encourage you to write your own **Portable Workspace**._