Документация как код — хранение статей и регламентов в репозитории в Markdown (или аналогичном формате), сборка в сайт через MkDocs/Sphinx/Docusaurus и публикация по тому же процессу, что и код: PR, ревью, CI. В статье — зачем это DevOps и как связать с базой знаний и RAG.

Зачем документация в Git

Версионирование: история изменений и авторство. Один источник правды рядом с кодом — при изменении API обновляется и описание. Ревью документации в том же PR, что и код. Сборка в CI — актуальный сайт документации после каждого мержа.

Инструменты

Инструмент	Формат	Когда выбирать
MkDocs	Markdown	Простая документация, темы (Material), плагины (поиск); быстрый старт
Sphinx	reStructuredText, MyST	Техдок с автогенерацией из docstrings, API-документация
Docusaurus	Markdown, MDX	React-стек, версионирование документации, блог

Выбор зависит от стека и предпочтений команды; главное — единый формат и процесс обновления.

Минимальный MkDocs и CI

Пример mkdocs.yml и рабочий workflow GitHub Actions для сборки и публикации при мерже в main:

# mkdocs.yml
site_name: My Project Docs
nav:
  - Home: index.md
  - Runbooks: runbooks/
plugins:
  - search

# .github/workflows/docs.yml
name: Build and publish docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install mkdocs mkdocs-material
      - run: mkdocs build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

Альтернатива: выкладка site/ в S3 или внутренний хостинг — замените последний шаг на aws s3 sync site/ s3://bucket/docs/ или свой скрипт. Собранные Markdown или HTML можно пайпить в пайплайн индексации RAG.

Связка с RAG

Собранные Markdown или HTML можно пайпить в пайплайн индексации: чанкинг, эмбеддинги, загрузка в векторную БД. Тогда чат по базе знаний отвечает по актуальной документации без ручного копирования. Документация как код + RAG — минимальный цикл: пишем в репо, CI собирает и индексирует.

flowchart LR A[Git: Markdown] --> B[CI: mkdocs build] B --> C[Статика] C --> D[Публикация] C --> E[Пайплайн индексации] E --> F[RAG-чат]

Практики применения

Храните документацию в том же репо, что и код; сборку и публикацию вынесите в CI (GitHub Actions, GitLab CI).
Подключите вывод собранной документации к пайплайну индексации RAG — чат по архиву будет отвечать по актуальным регламентам и API.

Кратко: документация в Git, сборка в CI, публикация автоматически. MkDocs/Sphinx/Docusaurus — на выбор. Подключите вывод документации в RAG — чат по архиву будет использовать актуальные регламенты и API.