Merge pull request #15 from media-code/docs

Docs

docs/.gitignore

@@ -0,0 +1 @@
+/.jekyll-cache

docs/_config.yml

@@ -0,0 +1,16 @@
+title: workspace
+description: Extendible workspace configurator for Laravel
+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
+
+callouts:
+  note:
+    title: note
+    color: purple
+  warning:
+    title: warning
+    color: red

docs/api-reference.md

@@ -0,0 +1,78 @@
+---
+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)
+    }
+}
+```

docs/default-integrations.md

@@ -0,0 +1,33 @@
+---
+nav_order: 3
+---
+
+# Integrations
+
+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.
+
+## EditorDefaults
+
+## PHPCodeSniffer
+
+## PrettierBlade
+
+## PHPCSFixer
+
+## IDEHelper
+
+## Workflows
+
+## Larastan
+
+## Aliases
+
+## TLint
+
+## Pint

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'],
+                ]
+            );
+    })
+];
+```

docs/index.md

@@ -0,0 +1,60 @@
+---
+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)
+[![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)
+
+Effortlessly keep linters, fixers, static analysis, CI workflows, editor integrations and more in sync across all your teams & projects.
+
+## Quickstart
+
+```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
+```
+
+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
+
+## 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**._
+
+<!-- Move to Portable Workspace section -->
+<!-- When you use the `update` command with your own _Portable Workspace_ you'll have to manually update your _Portable Workspace_ package. The update command only takes care of upgrading your Integration's composer & npm dependencies before rebuilding the config files. -->
+
+## 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.

docs/portable-workspaces.md

@@ -0,0 +1,24 @@
+---
+nav_order: 4
+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