WIP: chore(root): new docs docusaurus + swagger ui

.github/workflows/deploy.yml

@@ -1,42 +1,33 @@
-name: Deploy
+name: Deploy Docusaurus
 
 on:
   push:
-    branches: [ 'master' ]
+    branches: [ 'main/open-api' ]
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    env:
-      ruby-version: 3.3.8
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
       with:
-        ruby-version: ${{ env.ruby-version }}
+        node-version: 18
+        cache: yarn
+    - name: Install dependencies
+      run: yarn install --frozen-lockfile
 
+    - name: Clean old docs
+      run: yarn clean:docs
 
-    - uses: actions/cache@v4
-      with:
-        path: vendor/bundle
-        key: gems-${{ runner.os }}-${{ env.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          gems-${{ runner.os }}-${{ env.ruby-version }}-
-          gems-${{ runner.os }}-
-
-    - run: bundle config set deployment 'true'
-    - name: bundle install
-      run: |
-        bundle config path vendor/bundle
-        bundle install --jobs 4 --retry 3
+    - name: Generate API docs
+      run: yarn genapi
 
-    - run: bundle exec middleman build
+    - name: Build site
+      run: yarn build
 
-    - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./build
-        keep_files: true
+    - name: Deploy to GitHub Pages
+      run: yarn deploy
+      env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,29 +1,26 @@
-*.gem
-*.rbc
-.bundle
-.config
-coverage
-InstalledFiles
-vendor/bundle
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
+# Dependencies
+node_modules
+
+# Production
+build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
 *.DS_STORE
-build/
-.cache
-.vagrant
-.sass-cache
+*.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
 
-# YARD artifacts
-.yardoc
-_yardoc
-doc/
-.idea/
-.vscode
+docs/*
+yarn.lock
 
-# Vagrant artifacts
-ubuntu-*-console.log
+.idea

CONTRIBUTING.md

@@ -1,15 +1,100 @@
-# Contributing
+<div dir="rtl">
 
-## Development
-To install dependencies, after installing `ruby`, install bundle with `gem install bundler` and then
-use `bundle install` to install dependencies.
+### راهنمای اضافه کردن سکشن جدید به OpenAPI و مستندات Docusaurus
 
-Now you can start editing files in `source` directory. Launch a server with `make serve` to view the
-resulting HTML in your browser.
+#### I. افزودن اندپوینت جدید به فایل OpenAPI
 
-To build the site run `make build`. This will generate site's static files in `build` folder.
+1. در فایل OpenAPI مربوطه، اندپوینت جدید را در بخش `paths` و بر اساس متد مورد نظر (`post`, `get`, `delete`, …) اضافه کنید.
+2. برای قابل‌مشاهده بودن اندپوینت در سایدبار، مقدار `tag` آن را مطابق با تگ تعریف‌شده برای همان فایل OpenAPI تنظیم کنید.
+3. در صورت نیاز:
+    - `summary` و `description` اندپوینت را کامل بنویسید.
+    - اگر اندپوینت خصوصی است، در بخش `security` برای آن `TokenAuth` اضافه کنید.
+    - اگر به هدرها یا بدنهٔ درخواست نیاز است، `requestBody` را تعریف کنید.
+    - در نهایت، پارامترها (`parameters`) و انواع ریسپانس‌های (`responses`) مربوط به اندپوینت را اضافه کنید.
 
-# References
-* https://github.com/lord/slate/wiki/
-* https://developer.tradegecko.com/docs.html
-* https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers
+> اگر فایل جدیدی اضافه نمی‌کنید و فقط روی فایل‌های موجود ویرایش انجام می‌دهید، می‌توانید مرحلهٔ II و III را نادیده بگیرید و مستقیم به مرحله IV بروید.
+
+#### II. افزودن فایل OpenAPI جدید به تنظیمات `docusaurus-plugin-openapi-docs`
+
+اگر فایل OpenAPI جدیدی اضافه می‌کنید:
+
+1. فایل جدید را در تنظیمات پلاگین `docusaurus-plugin-openapi-docs` در فایل `docusaurus.config.ts` ثبت کنید.
+2. برای هر ورودی جدید، مقادیر زیر را تنظیم کنید:
+    - `specPath`: مسیر فایل OpenAPI در پوشهٔ `openapi`
+    - `outputDir`: مسیر پوشهٔ خروجی که طبق کنوانسیون باید به صورت `docs/<key>` باشد
+    - `sidebarOptions`: تنظیمات نحوهٔ نمایش در سایدبار. با توجه به این‌که در مرحلهٔ قبل تگ اندپوینت‌ها را مشخص کرده‌ایم، این بخش معمولاً به صورت زیر تنظیم می‌شود:
+
+</div>
+
+```ts
+sidebarOptions: {
+  groupPathsBy: "tag",
+  categoryLinkSource: "tag",
+}
+```
+
+<div dir="rtl">
+
+
+خروجی این بخش باید بصورت زیر باشد:
+</div>
+
+```ts
+<file_name>: {
+    specPath: "openapi/<file_name>.yaml",
+        outputDir: "docs/<file_name>",
+        sidebarOptions: {
+        groupPathsBy: "tag",
+            categoryLinkSource: "tag",
+    },
+} satisfies OpenApiPlugin.Options,
+```
+
+<div dir="rtl">
+
+3. با توجه به ساختار TypeScript، بهتر است نوع تنظیمات پلاگین را نیز با `OpenApiPlugin.Options` مشخص کنید.
+
+در این مرحله امکان جنریت کردن مستندات مربوط به فایل جدید توسط Docusaurus فراهم می‌شود. برای این کار می‌توانید دستور زیر را اجرا کنید:
+
+</div>
+
+```bash
+  yarn genapi
+```
+
+<div dir="rtl">
+
+#### III. بررسی خروجی جنریت‌شده
+
+1. اگر فایل‌ها بدون خطا جنریت شدند، بسته به مقداری که برای `outputDir` تنظیم کرده‌اید، می‌توانید دایرکتوری متناظر را در مسیر `./docs` مشاهده کنید.
+2. پلاگین `docusaurus-plugin-openapi-docs` برای هر پوشهٔ خروجی، یک فایل `sidebar` نیز تولید می‌کند:
+    - این فایل سایدبار را ابتدا در روت پروژه به تنظیمات سایدبارها اضافه کنید.
+    - سپس مانند سایر سایدبارها، آیتم‌های آن را (از ایندکس دوم به بعد) به لیست `items` اضافه کنید.
+    - با تغییر ترتیب آیتم‌ها در لیست `items`، ترتیب نمایش در سایدبار نیز تغییر خواهد کرد.
+
+#### IV. به‌روزرسانی تغییرات و اجرای پروژه
+
+1. تغییرات مربوط به این کار را در فایل زیر ثبت کنید:
+
+   [`src/pages/changelog.md`](src/pages/changelog.md)
+
+2. برای مشاهدهٔ بیلد لوکال، دستور زیر را اجرا کنید:
+
+</div>
+
+```bash
+  yarn dev
+```
+
+<div dir="rtl">
+
+3. پس از تأیید نهایی تغییرات، آن‌ها را با برنچ زیر مرج کنید.
+</div>
+
+```text
+  main/open-api
+```
+
+<div dir="rtl">
+
+</div>