Update docs

realodix · Jul 10, 2024 · 80acedc · 80acedc
1 parent 11acdf5
commit 80acedc
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
-# Realodix Relax
+# Relax - Centralized PHP-CS-Fixer Rule Config
 
 ![PHPVersion](https://img.shields.io/badge/PHP-7.4%20|%20%5E8.0-777BB4.svg?style=flat-square)
 ![Packagist Version (custom server)](https://img.shields.io/packagist/v/realodix/relax)
 ![Build Status](../../actions/workflows/ci.yml/badge.svg)
 
-**Realodix Relax** is built on top of [`PHP-CS-Fixer`][php-cs-fixer] and makes it simple to to sharing identical PHP CS Fixer rules across all of your projects without copy-and-pasting configuration files.
+**Relax** is built on top of [`PHP-CS-Fixer`](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) and makes it easy to provide a standardized way to apply coding standards across multiple projects, ensuring consistency and adherence to best practices.
 
+By using predefined rulesets, it simplifies the setup process and allows teams to quickly integrate PHP-CS-Fixer into their development workflow.
 
 ## Installation
 
@@ -27,24 +28,35 @@ For more details, see PHP-CS-Fixer [documentation](https://github.com/PHP-CS-Fix
 
 ## Configuring Relax
 
-In your PHP CS Fixer configuration file, use the following contents:
+You can easily create your own rule set by extending the [`Realodix\Relax\RuleSet\AbstractRuleSet`](src/RuleSet/AbstractRuleSet.php) class and use it! See [docs/example_ruleset.md](docs/example_ruleset.md) for an example of how to create your own rule set.
 
 ```php
 <?php
 
 use Realodix\Relax\Config;
+use Vendor\Package\MyRuleSet;
+
+return Config::create(new MyRuleSet)
+    ->setFinder(/* ... */);
+```
+
+Sometimes for big dirty projects, you want to implement some local rules without implementing a ruleset, why not.
 
+```php
 $localRules = [
     // ...
 ];
 
-return Config::create('laravel')
-    ->setRules($localRules);
+Config::create()
+    ->setRules($localRules)
+    ->setFinder(/* ... */);
 ```
 
-#### Rulesets
+For advanced configuration, see the [docs/advanced_configuration.md](docs/advanced_configuration.md)
+
+### Presets
 
-A ruleset is a named list of rules that can be used to fix code style issues in your code. To use ruleset in your PHP code, you need to use the `Realodix\Relax\RuleSet\Sets\` namespace.
+Preset defines a built-in set of rules that are ready to be used to fix code style issues in your code.
 
 | Ruleset                   | Description |
 | ------------------------- |-------------|
@@ -56,68 +68,8 @@ A ruleset is a named list of rules that can be used to fix code style issues in
 [rs_relax]: src/RuleSet/Sets/Realodix.php
 [rs_spatie]: src/RuleSet/Sets/Spatie.php
 
-#### Custom Fixers
-
-- [kubawerlos/php-cs-fixer-custom-fixers](https://github.com/kubawerlos/php-cs-fixer-custom-fixers)
-
-:bulb: They're all registered, so you don't need to re-register via `registerCustomFixers()`.
-
-<!-- #### Finder Sets
-
-By default, Relax will inspect all `.php` files in your project except those in the `vendor` directory.
-
-| Preset | Description |
-| -------- |-------------|
-| [`Finder::base()`][doc_f_base] | The basic finder setup should be perfect for most PHP projects |
-| [`Finder::laravel()`][doc_f_laravel] | Inherits `Finder::base()` with some specific tweaks to Laravel |
-
-:bulb: By default, if finder is not set Relax will use `Finder::base()`.
-
-[doc_f_base]: docs/finders.md#finderbase
-[doc_f_laravel]: docs/finders.md#finderlaravel -->
-
-## Advanced Configuration
-See [docs/advanced_configuration.md](docs/advanced_configuration.md) for more details.
-
-
-## Custom Rule Set
-
-You can easily create your own rule set by extending the [`AbstractRuleSet`](src/RuleSet/AbstractRuleSet.php): class.
-
 ```php
-<?php
-
-use Realodix\Relax\RuleSet\AbstractRuleSet;
-
-class MyRuleSet extends AbstractRuleSet
-{
-    // This method is optional. If not implemented, Relax will use
-    // the class name itself as the ruleset name.
-    public function name(): string
-    {
-        // ...
-    }
-
-    public function rules(): array
-    {
-        // ...
-    }
-}
-```
-
-And use it!
-
-```php
-<?php
-
-use Realodix\Relax\Config;
-use Vendor\Package\MyRuleSet;
-
-$finder = (new PhpCsFixer\Finder())
-    ->in(__DIR__);
-
-return Config::create(new MyRuleSet())
-    ->setFinder($finder);
+Config::create('laravel')
 ```
 
 
@@ -131,5 +83,3 @@ Please report bugs to the [GitHub Issue Tracker](../../issues).
 ## License
 
 This package is licensed under the [MIT License](/LICENSE).
-
-[php-cs-fixer]: https://github.com/PHP-CS-Fixer/PHP-CS-Fixer
diff --git a/docs/advanced_configuration.md b/docs/advanced_configuration.md
@@ -11,6 +11,7 @@ You can find the full documentation on this page:
 
 use PhpCsFixer\Finder;
 use Realodix\Relax\Config;
+use Vendor\Package\MyRuleSet;
 
 // You can add or override rule set
 $localRules = [
@@ -35,26 +36,9 @@ $finder = Finder::create()
     ->notName('*.foo.php')
     ->append(['.php-cs-fixer.dist.php']);
 
-return Config::create('laravel')
+return Config::create(new MyRuleSet)
     ->setRules($localRules)
     ->setFinder($finder)
     ->setRiskyAllowed(false)
-    ->registerCustomFixers(new \PhpCsFixerCustomFixers\CustomFixer());
-```
-
-If you wish to completely define rules locally without using existing rule sets, you can do that:
-
-```php
-<?php
-
-use Realodix\Relax\Config;
-
-$localRules = [
-    '@PSR2'           => true,
-    'array_syntax'    => ['syntax' => 'short'],
-    'ordered_imports' => ['sort_algorithm' => 'alpha'],
-];
-
-return Config::create()
-    ->setRules($localRules);
+    ->registerCustomFixers(/* ... */);
 ```
diff --git a/docs/example_ruleset.md b/docs/example_ruleset.md
@@ -0,0 +1,44 @@
+1. **`name`**
+
+   This method is optional. If not implemented, Relax will use the class name itself as the ruleset name.
+
+2. **`rules`**
+
+   Define the PHP-CS-Fixer rules you want to use.
+
+   🧱 Resources:
+   - https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/rules/index.rst
+   - https://github.com/kubawerlos/php-cs-fixer-custom-fixers
+
+<br> <br>
+
+```php
+<?php
+
+use PhpCsFixerCustomFixers\Fixer;
+use Realodix\Relax\RuleSet\AbstractRuleSet;
+
+class MyRuleSet extends AbstractRuleSet
+{
+    public function name(): string
+    {
+        // ...
+    }
+
+    public function rules(): array
+    {
+        return [
+            '@PSR2' => true,
+            'array_syntax' => [
+                'syntax' => 'short'
+            ],
+            'blank_line_after_opening_tag' => true,
+            Fixer\NoImportFromGlobalNamespaceFixer::name() => true,
+            Fixer\NoLeadingSlashInGlobalNamespaceFixer::name() => true,
++           Fixer\PhpdocNoSuperfluousParamFixer::name() => true,
+
+            // ...
+        ];
+    }
+}
+```