Add docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,51 @@
+name: Deploy
+
+on:
+  workflow_dispatch: {}
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy-docs:
+    name: Deploy Docs
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build Docs
+        run: npm run docs:build
+
+      - name: Configure pages
+        uses: actions/configure-pages@v2
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/.vitepress/dist
+
+      - name: Deploy Docs
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -14,6 +14,10 @@ composer.phar
 coverage
 phpunit.xml
 
+# Docs
+cache
+package-lock.json
+
 # Others
 *.cache
 *.env

docs/.vitepress/config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "PHP Results",
+  description: "An opinionated result type for PHP",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Examples', link: '/markdown-examples' }
+    ],
+    sidebar: [
+      {
+        text: 'Examples',
+        items: [
+          { text: 'Markdown Examples', link: '/markdown-examples' },
+          { text: 'Runtime API Examples', link: '/api-examples' }
+        ]
+      }
+    ],
+    search: {
+      provider: 'local'
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/hereldar/php-results' }
+    ]
+  },
+  base: '/php-date-times/'
+})

docs/index.md

@@ -0,0 +1,57 @@
+
+PHP Results
+===========
+
+This package includes an opinionated version of the `Result` type of Rust. It is
+not intended to replicate the original type one-to-one, but to allow developers
+to handle the results in any way they choose.
+
+Use examples
+------------
+
+This `Result` type allows ignoring errors without a try-catch
+block:
+
+```php
+$value = getValue()->or(false);
+```
+
+It also allows throwing the error as a regular exception:
+
+```php
+doSomething()->orFail();
+```
+
+Or throwing a custom exception:
+
+```php
+doSomething()->orThrow(new MyException());
+```
+
+More complex flows can be handled by concatenating operations:
+
+```php
+$record = fetchRecord()
+    ->andThen(updateIt(...))
+    ->orElse(insertIt(...))
+    ->orFail();
+```
+
+And much more:
+
+```php
+$result = myFunction();
+
+if ($result->isError()) {
+    handleFailure($result->message());
+} else {
+    handleSuccess($result->value());
+}
+
+return match (true) {
+    $result instanceof Ok => $result->value(),
+    $result instanceof MyError => false,
+    default => throw new MyException(),
+}
+```
+

package.json

@@ -0,0 +1,10 @@
+{
+  "devDependencies": {
+    "vitepress": "^1.0.0-alpha.66"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}