RFC-006: Создание документационного сайта

Справка: Ознакомьтесь с шаблоном RFC для понимания спецификации RFC.

Резюме

Создание документационного сайта YaoXiang для интеграции разрозненной документации, обеспечения поддержки поиска, навигации, многоязычности и переключения версий.

Мотивация

Зачем нужна эта функция?

Текущая документация разбросана по нескольким каталогам и представлена только через GitHub Readme, что затрудняет новым пользователям поиск нужной информации, отсутствует поиск, а китайская и английская версии документации не синхронизированы.

Текущие проблемы

docs/
├── README.md              # Главный индекс (ограниченное содержимое)
├── tutorial/              # Учебные пособия
├── guides/               # Руководства
├── architecture/          # Документация по архитектуре
├── design/               # Документация по дизайну
├── examples/             # Примеры
├── plans/                # Планы реализации
├── implementation/       # Документация по реализации
├── maintenance/          # Документация по сопровождению
└── archived/             # Архив

Проблемы:

1. Нет единой точки входа, только GitHub Readme
2. Отсутствует поиск
3. Нет переключения версий, пользователи могут читать устаревшую документацию
4. .obsidian смешан с контролем версий

Предложение

Основной дизайн

┌─────────────────────────────────────────────────────────┐
│                    Фронтенд документационного сайта      │
│  ┌───────────┐ ┌───────────┐ ┌─────────────────────┐   │
│  │ Навбар    │ │ Боковая   │ │ Выпадающее меню     │   │
│  │           │ │ панель    │ │ переключения версий │   │
│  └───────────┘ └───────────┘ └─────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              VitePress + Starlight                      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              GitHub Pages (хостинг)                     │
└─────────────────────────────────────────────────────────┘

Структура каталогов (основной дизайн)

docs/
├── .vitepress/
│   ├── config.mts              # Конфигурация сайта
│   ├── navbar.ts              # Конфигурация навбара
│   └── sidebar/               # Конфигурация боковой панели
│       ├── zh.ts
│       └── en.ts
│
├── public/
│   ├── favicon.ico
│   └── logo.svg
│
├── zh/                        # Китайская документация
│   ├── index.md               # Китайская главная страница
│   ├── getting-started.md
│   ├── tutorial/
│   │   └── README.md
│   ├── reference/
│   │   └── README.md
│   ├── guide/
│   └── contributing.md
│
└── en/                        # Английская документация
    ├── index.md
    └── getting-started.md

Спецификация URL-путей (основной дизайн)

Сценарий	Формат URL	Описание
Последняя версия, китайский	/zh/getting-started/	Перенаправление на последнюю версию
Последняя версия, английский	/en/getting-started/	Перенаправление на последнюю версию
Указанная версия	/v0.5/zh/getting-started/	Префикс с номером версии
Главная страница	/zh/ или /en/	Языковая главная страница

Дизайн переключения версий:

Выпадающее меню переключения версий:
├── v0.6 (latest)
├── v0.5
├── v0.4
└── v0.3

Спецификация версионных путей (ключевое решение, которое сложно изменить впоследствии):

• Последняя версия: /zh/xxx/ → перенаправление на последнюю версию
• Указанная версия: /v0.5/zh/xxx/ → фиксированная версия
• Переключение версий в навбаре: переключение комбинации /v0.5/ и /zh/

Спецификация боковой панели

// docs/.vitepress/sidebar/zh.ts
export default {
  '/zh/tutorial/': [
    {
      text: 'Учебные пособия',
      items: [
        { text: 'Быстрый старт', link: '/zh/getting-started' },
        { text: 'Основы', link: '/zh/tutorial/basics' },
      ],
    },
  ],
  '/zh/reference/': [
    {
      text: 'Справочник',
      items: [{ text: 'Встроенные функции', link: '/zh/reference/builtins' }],
    },
  ],
};

Интеграция CI/CD

# .github/workflows/docs-deploy.yml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**', '!.obsidian/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
        working-directory: docs
      - run: npm run build
      - uses: actions/deploy-pages@v4
        with:
          build_dir: docs/.vitepress/dist

Детальный дизайн

Конфигурация навбара

// docs/.vitepress/navbar.ts
export default [
  { text: 'Начало', link: '/zh/getting-started' },
  { text: 'Учебные пособия', link: '/zh/tutorial/' },
  { text: 'Справочник', link: '/zh/reference/' },
  { text: 'Дизайн', link: '/zh/design/' },
  { text: 'GitHub', link: 'https://github.com/yaoxiang-lang/yaoxiang' },
];

Конфигурация сайта

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress';
import starlight from '@astrojs/starlight';

export default defineConfig({
  title: 'YaoXiang',
  description: 'Язык программирования, ориентированный на будущее',

  locales: {
    root: { label: '中文', lang: 'zh-CN', link: '/zh/' },
    en: { label: 'English', lang: 'en-US', link: '/en/' },
  },

  // Локальный поиск
  plugins: [
    starlight({
      title: 'YaoXiang',
      localSearch: {},
    }),
  ],

  // Ссылка для редактирования
  editLink: {
    pattern: 'https://github.com/yaoxiang-lang/yaoxiang/edit/main/docs/:path',
  },
});

Компромиссы

Преимущества

• Профессиональный документационный сайт улучшает имидж проекта
• Пользователи быстро находят нужную информацию
• Локальный поиск бесплатен и достаточен
• Поддержка многоязычности для международного сообщества
• Переключение версий предотвращает чтение устаревшей документации

Недостатки

• Затраты на сопровождение: требуется поддержка конфигурации сайта
• Введение технологического стека: Node.js

Альтернативные решения

Решение	Почему не выбрано
GitHub Wiki	Плохой поиск, низкая кастомизация
Только README	Нет поиска, нет навигации
Docusaurus	Слишком тяжёлый, медленный старт

Стратегия реализации

Разделение на этапы

Этап	Содержание	Статус
P0	Инициализация конфигурации VitePress + Starlight	Сделать
P0	Настройка структуры каталогов, навбара, боковой панели	Сделать
P0	Миграция README + Быстрый старт	Сделать
P0	CI/CD автоматическое развёртывание на GitHub Pages	Сделать
P1	Миграция учебных пособий, справочной документации	Сделать
P1	Настройка меню переключения версий	Сделать
P2	Дополнить английскую документацию	Сделать

Зависимости

Нет внешних RFC зависимостей

Риски

Риск	Влияние	Меры по смягчению
Потеря контента	Очень велико	Полная резервная копия перед миграцией

Открытые вопросы

Нет - Все решения приняты

---

Приложения

Приложение A: Запись решений по дизайну

Решение	Решение	Дата	Записал
Выбор SSG	VitePress + Starlight	2025-02-07	晨煦
Платформа хостинга	GitHub Pages	2025-02-07	晨煦
Решение для поиска	Локальный поиск	2025-02-07	晨煦
Структура многоязычности	Префиксы /zh/ и /en/	2025-02-07	晨煦
Версионные пути	Формат /v0.5/zh/	2025-02-07	晨煦

---

Ссылки

• Документация VitePress
• Документация Starlight