Merge pull request #612 from wayofdev/feat/docs

Author: lotyp

Makefile

@@ -190,3 +190,11 @@ test-cc: ## Run project php-unit and pest tests in coverage mode and build repor
 docs-deps-update: ## Check for outdated dependencies and automatically update them using pnpm
 	cd docs && $(NPM_RUNNER) run deps:update
 .PHONY: docs-deps-update
+
+docs-deps-install: ## Install dependencies for documentation using pnpm
+	cd docs && $(NPM_RUNNER) install
+.PHONY: docs-deps-install
+
+docs-up: ## Start documentation server
+	cd docs && $(NPM_RUNNER) dev
+.PHONY: docs-up

docs/pages/contributing.mdx

@@ -8,7 +8,7 @@ The latest changes are always in master branch, so please make your Pull Request
 
 ## 💻 Workflow
 
-<Callout type="warning">
+<Callout type="warning" emoji="⚠️">
     Please feature/fix/update... into individual PRs (not one changing everything)
 </Callout>
 

docs/pages/services/factories.mdx

@@ -1,6 +1,6 @@
 import { Callout } from "nextra-theme-docs";
 
-Like [Eloquent Factories](https://laravel.com/docs/10.x/eloquent-factories) this package enables you to define factories for your database models, integrating Cycle ORM with Laravel's elegant syntax and functionality.
+Like [Eloquent Factories](https://laravel.com/docs/10.x/eloquent-factories) this package enables you to define factories for your entities, integrating Cycle ORM with Laravel's elegant syntax and functionality.
 
 This feature is available through the [wayofdev/laravel-cycle-orm-factories](https://github.com/wayofdev/laravel-cycle-orm-factories), be sure to check [installation](/installation#-database-factories-optional) instructions.
 
@@ -163,7 +163,7 @@ State manipulation methods allow you to define discrete modifications that can b
 
 State transformation methods typically call the state method provided by `WayOfDev\DatabaseSeeder\Factories\AbstractFactory` class. The state method accepts a closure which will receive the array of raw attributes defined for the factory and should return an array of attributes to modify:
 
-<Callout type="note">
+<Callout type="info" emoji="💡">
     💡 It is non-destructive, it will only update the properties passed in the returned array and will not remove any properties from the definition array.
 </Callout>
 
@@ -436,7 +436,7 @@ class PostFactory extends AbstractFactory
     }
 
     // example with User created by factory
-    public function withUser(UserFactory $userFactory): self
+    public function withUser(): self
     {
         return $this->state(fn (Generator $faker, array $definition) => [
             'user' => UserFactory::new()->createOne(), // or makeOne to allow cascade persisting

docs/pages/services/seeders.mdx

@@ -1 +1,52 @@
-# Database Seeders
+import {Callout} from "nextra-theme-docs";
+
+## Introduction
+
+Laravel includes the ability to seed your database with data using seed classes. All seed classes are stored in the database/seeders directory.
+Same as in Laravel with Eloquent, you can use default Laravel seeders to seed your data into the database, by using CycleORM database factories.
+
+<Callout type="info" emoji="💡">
+Check also [Laravel Database Seeders](https://laravel.com/docs/10.x/seeding) documentation.
+</Callout>
+
+## ✏️ Writing Seeders
+
+Seeder classes are generated, same as it is in Laravel, using the `make:seeder` Artisan command. These classes are stored in the database/seeders directory. Seeder classes may have any name you wish, but probably should follow some sensible convention, such as `PostSeeder`, `CommentSeeder`, `UserSeeder` etc.
+
+```bash
+php artisan make:seeder PostSeeder
+```
+
+## ⚡️ Using Entity Factories
+
+Best way to use seeders is to use Entity Factories, which is provided by [wayofdev/laravel-cycle-orm-factories](https://github.com/wayofdev/laravel-cycle-orm-factories). You can create a factory for each of your entities and use them to seed your database.
+
+In this documentation section we will use examples from [Factories](/services/factories) documentation page.
+
+For example, let's create 20 posts and 10 comments for each post:
+
+```php
+<?php
+
+namespace Database\Seeders;
+
+use Illuminate\Database\Seeder;
+use Database\Factories\Post\PostFactory;
+use Database\Factories\Post\Comment\CommentFactory;
+use Database\Factories\User\UserFactory;
+
+final class PostSeeder extends Seeder
+{
+    public function run(): void
+    {
+        $author = UserFactory::new()->createOne();
+        $posts = PostFactory::new()->withUser($author)->times(20)->create();
+
+        $collection->each(function (Post $post): void {
+            CommentFactory::new([
+                'post' => $post,
+            ])->times(10)->create();
+        });
+    }
+}
+```

docs/pages/usage/console-commands.mdx

@@ -1,23 +1,115 @@
-# Console Commands
+import {Callout} from "nextra-theme-docs";
 
 This package includes CycleORM commands implemented as Laravel Console Commands, you can use them to manage your database schema and perform migrations.
 
-The package extends Laravel's artisan commands, introducing a set of commands specifically designed for managing Cycle ORM migrations and database schema. These commands are intuitive for Laravel developers and follow the framework's conventions.
+The package extends Laravel's artisan commands, introducing a set of commands specifically designed for managing CycleORM migrations and database schema. These commands are intuitive for Laravel developers and follow the framework's conventions.
 
 
 ## 🛠️ Commands for Migrations
 
-The package includes a set of commands for managing migrations. These commands are similar to Laravel's migration commands, but they are designed to work with Cycle ORM.
+Migration commands are essential for managing your database's evolution over time. They allow for the creation, execution, rollback, and status checking of migrations.
 
-### Table of Contents
+### Command List
 
-| Command                  | Description                                                                                                     |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------|
-| `cycle:migrate`          | Executes pending migrations. Use the --one flag to execute only the first pending migration.                    |
-| `cycle:migrate:replay`   | Replays migrations by rolling them back and then re-applying them. Use the --all flag to replay all migrations. |
-| `cycle:migrate:rollback` | Rolls back the last batch of migrations by default. Use the --all flag to roll back all migrations.             |
-| `cycle:migrate:init`     | Initializes the migration system by creating the necessary migrations table.                                    |
-| `cycle:migrate:status`   | Displays the status of all migrations, indicating which have been applied.                                      |
-| `cycle:migrate:fresh`    | Drops all tables and re-runs all migrations, providing a clean slate. ⚠️                                        |
+| Command                  | Description                                                                                                       |
+|--------------------------|-------------------------------------------------------------------------------------------------------------------|
+| `cycle:migrate:init`     | Initializes the migration system by creating the necessary migrations table.                                      |
+| `cycle:migrate`          | Executes pending migrations. Use the `--one` flag to execute only the first pending migration.                    |
+| `cycle:migrate:replay`   | Replays migrations by rolling them back and then re-applying them. Use the `--all` flag to replay all migrations. |
+| `cycle:migrate:rollback` | Rolls back the last batch of migrations by default. Use the `--all` flag to roll back all migrations.             |
+| `cycle:migrate:status`   | Displays the status of all migrations, indicating which have been applied.                                        |
+| `cycle:migrate:fresh`    | Drops all tables and re-runs all migrations, providing a clean slate. ⚠️                                          |
 
-### Usage
+### Initializing Migrations
+
+`cycle:migrate:init`
+
+This command is your starting point for migration management. It initializes the migration system by creating the necessary migrations table in your database, ensuring that you can start tracking and executing migrations.
+
+#### Usage:
+
+```bash
+php artisan cycle:migrate:init
+```
+
+### Running Migrations
+
+`cycle:migrate`
+
+To apply pending migrations to your database, use the `cycle:migrate` command. This will execute all migrations that have not yet been applied, updating your database schema accordingly.
+
+#### Usage:
+
+```bash
+php artisan cycle:migrate
+```
+
+#### Options:
+
+`--one`: Executes only the first pending migration, allowing for more granular control over the migration process.
+
+### Replaying Migrations
+
+`cycle:migrate:replay`
+
+This command facilitates the replaying of migrations by first rolling them back and then re-applying them. It's particularly useful for development environments where you need to quickly test changes to migrations.
+
+#### Usage:
+
+```bash
+php artisan cycle:migrate:replay
+```
+
+#### Options:
+
+`--all`: Replays all migrations, effectively refreshing your entire database schema.
+
+
+### Rolling Back Migrations
+
+`cycle:migrate:rollback`
+
+To undo the last batch of migrations, you can use the `cycle:migrate:rollback` command. This is useful when you need to revert changes made by the most recent migrations.
+
+#### Usage:
+
+```bash
+php artisan cycle:migrate:rollback
+```
+
+#### Options:
+
+`--all`: Rolls back all migrations, allowing you to revert your database schema to its initial state.
+
+
+### Checking Migration Status
+
+`cycle:migrate:status`
+
+Keeping track of which migrations have been applied is crucial for database management. The `cycle:migrate:status` command displays the status of all migrations, indicating which have been applied and which are pending.
+
+#### Usage:
+
+```bash
+php artisan cycle:migrate:status
+```
+
+### Fresh Schema Command
+
+`cycle:migrate:fresh`
+
+When you need to start from a clean slate, the `cycle:migrate:fresh` command drops all tables from the database and re-runs all migrations. This is particularly useful for resetting the database to a known state during development or testing.
+
+#### Usage:
+
+```bash
+php artisan cycle:migrate:fresh
+```
+
+<Callout type="warning" emoji="⚠️">
+    Be cautious when using the `cycle:migrate:fresh` command, as it will permanently delete all data in your database.
+</Callout>
+
+#### Options:
+
+`--seed`: Seeds the database after running the migrations, populating it with initial data.