Merge pull request #628 from wayofdev/feat/docs

Author: lotyp

docs/.npmrc

@@ -0,0 +1 @@
+enable-pre-post-scripts=true

docs/components/asciinema-player/player.tsx

@@ -0,0 +1,20 @@
+import "asciinema-player/dist/bundle/asciinema-player.css";
+import React, { useEffect, useRef } from 'react';
+
+const AsciinemaPlayer = ({ src, options = {}, ...rest }) => {
+    const ref = useRef(null);
+
+    useEffect(() => {
+        if (typeof window !== 'undefined') {
+            import('asciinema-player').then((module) => {
+                if (ref.current) {
+                    module.create(src, ref.current, options);
+                }
+            });
+        }
+    }, [src, JSON.stringify(options)]);
+
+    return <div ref={ref} {...rest} />;
+};
+
+export default AsciinemaPlayer;

docs/next-sitemap.config.js

@@ -0,0 +1,5 @@
+/** @type {import('next-sitemap').IConfig} */
+module.exports = {
+    siteUrl: 'https://laravel-cycle-orm-adapter.wayof.dev',
+    generateRobotsTxt: true,
+}

docs/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
+    "postbuild": "next-sitemap",
     "start": "next start",
     "deps:update": "pnpm dlx npm-check-updates --configFileName .ncurc.yml -u --deep --mergeConfig && pnpm install"
   },
@@ -21,7 +22,9 @@
   "dependencies": {
     "@heroicons/react": "^2.1.1",
     "@vercel/analytics": "^1.2.2",
+    "asciinema-player": "^3.7.0",
     "next": "^14.1.3",
+    "next-sitemap": "^4.2.3",
     "nextra": "latest",
     "nextra-theme-docs": "latest",
     "react": "^18.2.0",

docs/pages/_app.tsx

@@ -1,7 +1,6 @@
 import { Analytics } from '@vercel/analytics/react'
 import type { AppProps } from 'next/app'
 import type { ReactElement } from 'react'
-
 import '../style.css'
 
 function Nextra({ Component, pageProps }: AppProps): ReactElement {

docs/pages/console-commands/database-commands.mdx

@@ -1,9 +1,10 @@
 import {Callout} from "nextra-theme-docs";
 import {OptionTable} from "../../components/env-table";
+import Image from 'next/image';
 
 # Database Commands
 
-The following commands are available for managing the database.
+Database commands provides tooling to manage and inspect your databases.
 
 ### Command Reference Table
 
@@ -34,3 +35,39 @@ export const commands = [
     }))}
     columns={columns}
 />
+
+### Listing Databases
+
+`cycle:db:list`
+
+This command provides a comprehensive list of all databases, along with their tables and the count of records in each table.
+
+#### Usage
+
+```bash
+php artisan cycle:db:list
+```
+
+#### Example
+
+<Image src="/images/command.cycle-db-list.png" alt="Listing Databases" width={1882} height={1016} />
+
+### Describing Table Schema
+
+`cycle:db:table`
+
+To get detailed information about the schema of a specific table, use the cycle:db:table command. This includes column names, types, and other relevant metadata.
+
+#### Usage
+
+```bash
+php artisan cycle:db:table your_table_name
+```
+
+#### Options
+
+`--d|database`: The name of the database to use. If not provided, the default database will be used.
+
+#### Example
+
+<Image src="/images/command.cycle-db-table.png" alt="Listing Table Contents" width={1882} height={1016} />

docs/pages/console-commands/migration-commands.mdx

@@ -1,5 +1,6 @@
 import {Callout} from "nextra-theme-docs";
 import {OptionTable} from "../../components/env-table";
+import AsciinemaPlayer from "../../components/asciinema-player/player";
 
 # Migration Commands
 
@@ -65,7 +66,27 @@ php artisan cycle:migrate
 
 #### Options
 
-`--one`: Executes only the first pending migration, allowing for more granular control over the migration process.
+- `--one`: Executes only the first pending migration, allowing for more granular control over the migration process.
+
+#### Example
+
+Recording shows the visualization of applying migrations to the database.
+
+<br/>
+
+<AsciinemaPlayer
+    src="https://asciinema.org/a/sRNJPTQZTHxRoiGVAqxKvR48K.cast"
+    options={{
+        idleTimeLimit: 2,
+        preload: true,
+        loop: 0,
+        speed: 1.0,
+        theme: 'monokai',
+        rows: 28,
+        cols: 120,
+        poster: "npt:0:03"
+    }}
+/>
 
 ### Replaying Migrations
 
@@ -81,7 +102,7 @@ php artisan cycle:migrate:replay
 
 #### Options
 
-`--all`: Replays all migrations, effectively refreshing your entire database schema.
+- `--all`: Replays all migrations, effectively refreshing your entire database schema.
 
 
 ### Rolling Back Migrations
@@ -98,7 +119,7 @@ php artisan cycle:migrate:rollback
 
 #### Options
 
-`--all`: Rolls back all migrations, allowing you to revert your database schema to its initial state.
+- `--all`: Rolls back all migrations, allowing you to revert your database schema to its initial state.
 
 
 ### Checking Migration Status
@@ -131,4 +152,4 @@ php artisan cycle:migrate:fresh
 
 #### Options
 
-`--seed`: Seeds the database after running the migrations, populating it with initial data.
+- `--seed`: Seeds the database after running the migrations, populating it with initial data.

docs/pages/console-commands/orm-commands.mdx

@@ -1,9 +1,10 @@
 import {Callout} from "nextra-theme-docs";
 import {OptionTable} from "../../components/env-table";
+import AsciinemaPlayer from "../../components/asciinema-player/player";
 
 # ORM Commands
 
-The following commands are available for managing the ORM.
+ORM commands facilitate the management of the Object-Relational Mapping layer, allowing for the initialization and updating of schemas, migration generation, schema visualization, and direct synchronization with the database.
 
 ### Command Reference Table
 
@@ -36,3 +37,105 @@ export const commands = [
     }))}
     columns={columns}
 />
+
+### Initializing or Updating ORM Schema
+
+`cycle:orm`
+
+This command initializes or updates the Cycle ORM schema by analyzing the database structure and annotated classes.
+
+#### Usage
+
+```bash
+php artisan cycle:orm
+```
+
+### Generating ORM Schema Migrations
+
+`cycle:orm:migrate`
+
+Use this command to generate migrations based on the current ORM schema. It's a crucial step for evolving the database schema in a controlled manner.
+
+#### Usage
+
+```bash
+php artisan cycle:orm:migrate
+```
+
+#### Options
+
+- `--r|run` - Automatically run generated migration.
+- `--s|split` - Split migration into multiple files (one per table).
+
+#### Example
+
+Recording shows migration file generation on existing Domain Entities and their relationships.
+
+<br/>
+
+<AsciinemaPlayer
+    src="https://asciinema.org/a/Q7uli4kvEkbbzqt4LBLNlCCkE.cast"
+    options={{
+        idleTimeLimit: 2,
+        preload: true,
+        loop: 0,
+        speed: 1.0,
+        theme: 'monokai',
+        rows: 28,
+        cols: 120,
+        poster: "npt:0:04"
+    }}
+/>
+
+### Displaying ORM Schema
+
+`cycle:orm:render`
+
+To visualize the current ORM schema directly in your console, use the `cycle:orm:render` command. This can help with understanding the structure and relationships defined in your ORM.
+
+#### Usage
+
+```bash
+php artisan cycle:orm:render
+```
+
+#### Options
+
+- `--nc|no-color` - Display output without colors.
+- `--p|php` - Display output as PHP code.
+
+#### Example
+
+Recording shows the visualization of the ORM schema in the console for existing `App/Entities/Post` entity.
+
+<br/>
+
+<AsciinemaPlayer
+    src="https://asciinema.org/a/0ZTAlr5EWbVlll86A4EKm35N1.cast"
+    options={{
+        idleTimeLimit: 2,
+        preload: true,
+        loop: 0,
+        speed: 1.0,
+        theme: 'monokai',
+        rows: 28,
+        cols: 120,
+        poster: "npt:0:03"
+    }}
+/>
+
+### Synchronizing ORM Schema with Database
+
+`cycle:orm:sync`
+
+This command directly synchronizes the Cycle ORM schema with the database. It bypasses the migration system and applies changes directly, which can be risky.
+
+#### Usage
+
+```bash
+php artisan cycle:orm:sync
+```
+
+<Callout type="warning" emoji="⚠️">
+    Be cautious when using the `cycle:orm:sync` command, as it directly alters the database schema and can potentially lead to data loss.
+</Callout>