update-docs-system

Комплексная система автоматизации документации для проектов с Markdown файлами. Поддерживает автоматическое создание оглавлений, определение авторства, русскую навигацию и интеграцию с различными системами CI/CD.

🚀 Возможности

• Автоматическое создание оглавления - сканирует Markdown файлы и создает структурированное оглавление
• Система Content.json - генерирует метаданные документации с определением авторства
• Определение авторства - классифицирует файлы как созданные человеком, ИИ или автогенератором
• Русская навигация - добавляет ссылки "Домой" и "Назад" для удобной навигации
• Автогенераторы - поддержка создания и защиты автогенерированных файлов
• Множественные методы развертывания - PyPI, Git Submodule, Docker, GitHub Actions
• Автоматизация - GitHub Actions, pre-commit hooks, file watcher

📦 Установка и развертывание

Метод 1: PyPI пакет (Рекомендуется)

# Установка пакета
pip install update-docs-system

# Быстрая настройка в целевом репозитории
curl -sSL https://raw.githubusercontent.com/CoreTwin/docs_repo/main/scripts/setup_automation.sh | bash

# Или ручная настройка
update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md

Метод 2: Git Submodule

# В целевом репозитории
git submodule add https://github.com/CoreTwin/docs_repo.git tools/update-docs
git submodule update --init --recursive

# Использование
cd tools/update-docs
python -m update_docs.cli --docs ../../docs --content-json ../../content/Content.json --description-md ../../content/Description_for_agents.md

Метод 3: Docker контейнер

# Сборка образа
docker build -t update-docs:latest https://github.com/CoreTwin/docs_repo.git

# Использование в целевом репозитории
docker run --rm -v $(pwd):/workspace update-docs:latest \
  --docs docs \
  --content-json content/Content.json \
  --description-md content/Description_for_agents.md

Метод 4: GitHub Actions

Создайте .github/workflows/update-docs.yml в целевом репозитории:

name: 📚 Auto Update Documentation

on:
  push:
    branches: [main, master, develop]
    paths: ['**/*.md', 'docs/**/*']
  pull_request:
    branches: [main, master, develop]
    paths: ['**/*.md', 'docs/**/*']

jobs:
  update-docs:
    runs-on: ubuntu-latest
    
    steps:
    - name: 📥 Checkout repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
        token: ${{ secrets.GITHUB_TOKEN }}
    
    - name: 🐍 Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'
        cache: 'pip'
    
    - name: 📦 Install update-docs-system
      run: pip install update-docs-system
    
    - name: 🔍 Check for .md changes
      id: check_changes
      run: |
        if [ "${{ github.event_name }}" = "pull_request" ]; then
          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
        else
          CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || echo "")
        fi
        
        if echo "$CHANGED_FILES" | grep -E '\\.md$'; then
          echo "md_changed=true" >> $GITHUB_OUTPUT
          echo "📝 Markdown files changed, updating documentation..."
        else
          echo "md_changed=false" >> $GITHUB_OUTPUT
          echo "ℹ️  No markdown files changed"
        fi
    
    - name: 📚 Update documentation
      if: steps.check_changes.outputs.md_changed == 'true'
      run: |
        update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md
        echo "✅ Documentation updated successfully"
    
    - name: 💾 Commit updated documentation
      if: steps.check_changes.outputs.md_changed == 'true'
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action Bot"
        
        mkdir -p content
        git add content/Content.json content/Description_for_agents.md docs/ || true
        
        if git diff --staged --quiet; then
          echo "ℹ️  No changes to commit"
        else
          git commit -m "📚 Auto-update documentation"
          
          if [ "${{ github.event_name }}" != "pull_request" ]; then
            git push
            echo "✅ Documentation committed and pushed"
          fi
        fi

🔧 Использование

Современная система (Content.json)

# Обновление документации с генерацией Content.json
update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md

# Автоматическое определение системы по расширениям файлов
update-docs --docs docs --toc Content.json --toc-md Description_for_agents.md

Классическая система (toc.json)

# Создание JSON оглавления
update-docs --docs docs --toc toc.json

# Создание Markdown оглавления
update-docs --docs docs --toc toc.json --toc-md toc.md

# Генерация из существующего toc.json
update-docs --from-json --toc toc.json --toc-md toc.md

Справка по командам

# Получить полную справку
update-docs --help

# Примеры использования
update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md
update-docs --toc toc.json --toc-md toc.md

🤖 Автоматизация

Автоматическая настройка

Используйте скрипт автоматической настройки для быстрого развертывания:

# Скачать и запустить скрипт настройки
curl -sSL https://raw.githubusercontent.com/CoreTwin/docs_repo/main/scripts/setup_automation.sh | bash

# Или локально (если репозиторий уже клонирован)
bash scripts/setup_automation.sh

Скрипт автоматически:

• Устанавливает update-docs-system
• Создает структуру папок (docs/, content/, .github/workflows/, scripts/)
• Настраивает GitHub Actions workflow
• Устанавливает pre-commit hook
• Создает file watcher для разработки
• Генерирует примеры документации
• Запускает первое обновление

Pre-commit Hook

Создайте .git/hooks/pre-commit:

#!/bin/bash
echo "🔍 Checking for markdown file changes..."

md_files_changed=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.md$' || true)

if [ -n "$md_files_changed" ]; then
    echo "📝 Markdown files changed:"
    echo "$md_files_changed" | sed 's/^/  - /'
    echo ""
    echo "🔄 Updating documentation..."
    
    mkdir -p content
    
    if command -v update-docs &> /dev/null; then
        update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md
        update_result=$?
    else
        python3 -c "
try:
    from update_docs.core import update_content_system
    update_content_system('docs', 'content/Content.json', 'content/Description_for_agents.md')
    print('✅ Documentation updated via Python import')
except Exception as e:
    print(f'❌ Error: {e}')
    exit(1)
"
        update_result=$?
    fi
    
    if [ $update_result -eq 0 ]; then
        git add content/Content.json content/Description_for_agents.md docs/ 2>/dev/null || true
        echo "✅ Documentation updated and staged"
    else
        echo "❌ Failed to update documentation"
        exit 1
    fi
else
    echo "ℹ️  No markdown files changed, skipping documentation update"
fi

File Watcher для разработки

# Установка зависимостей
pip install watchdog

# Запуск file watcher
python scripts/watch_docs.py

Makefile для удобства

.PHONY: docs-update docs-watch docs-install docs-setup help

help:
	@echo "📚 Documentation Commands:"
	@echo "  docs-install  - Install update-docs-system"
	@echo "  docs-setup    - Setup automation (GitHub Actions, hooks, watcher)"
	@echo "  docs-update   - Update documentation once"
	@echo "  docs-watch    - Start file watcher for live updates"

docs-install:
	@echo "📦 Installing update-docs-system..."
	@pip install update-docs-system

docs-setup:
	@echo "🚀 Setting up update-docs automation..."
	@bash scripts/setup_automation.sh

docs-update:
	@echo "📚 Updating documentation..."
	@update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md
	@echo "✅ Documentation updated"

docs-watch:
	@echo "👀 Starting documentation watcher..."
	@python scripts/watch_docs.py

📁 Структура целевого репозитория

После настройки ваш репозиторий будет иметь следующую структуру:

target-repo/
├── docs/                           # Документация проекта
│   ├── README.md
│   ├── api/
│   └── guides/
├── content/                        # Метаданные документации
│   ├── Content.json               # Генерируется update-docs
│   └── Description_for_agents.md  # Генерируется update-docs
├── .github/
│   └── workflows/
│       └── update-docs.yml        # CI/CD для документации
├── scripts/
│   └── watch_docs.py              # File watcher для разработки
├── .git/hooks/
│   └── pre-commit                 # Pre-commit hook
├── Makefile                       # Команды для удобства
└── .gitignore                     # Исключения для временных файлов

🔍 Определение авторства

Система автоматически определяет тип автора для каждого файла:

• human - файлы, созданные человеком
• ai - файлы, созданные ИИ (по git истории или маркерам)
• generator - автогенерированные файлы (защищены от редактирования)
• mixed - файлы со смешанным авторством

Маркеры автогенерации

<!-- AUTO-GENERATED -->
<!-- AI-GENERATED -->
<!-- GENERATOR: script_name.py -->

📊 Content.json структура

[
  {
    "path": "docs/README.md",
    "title": "Project Documentation",
    "author": "human",
    "editable": true,
    "file_id": "readme-a1b2c3d4",
    "headers": [
      {
        "level": 1,
        "title": "Project Documentation",
        "id": "project-documentation",
        "parent_id": null,
        "excerpt": "Welcome to the project..."
      }
    ]
  }
]

🏠 Навигационные ссылки

Система автоматически добавляет русские навигационные ссылки:

• 🏠 Домой - ссылка на главную страницу
• ⬆️ Назад - ссылка на родительский документ

🧪 Тестирование интеграции

Проверьте работу системы в вашем репозитории:

# Тест установки пакета
pip install update-docs-system

# Тест базовой функциональности
update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md

# Проверка созданных файлов
ls -la content/
cat content/Content.json | head -20

# Тест внешнего развертывания
python test_external_deployment.py

🚀 Быстрый старт

1. Установите пакет:

   pip install update-docs-system
   

2. Запустите автоматическую настройку:

   curl -sSL https://raw.githubusercontent.com/CoreTwin/docs_repo/main/scripts/setup_automation.sh | bash
   

3. Или настройте вручную:

   # Создайте структуру папок
   mkdir -p docs content .github/workflows scripts
   
   # Запустите первое обновление
   update-docs --docs docs --content-json content/Content.json --description-md content/Description_for_agents.md
   
   # Зафиксируйте изменения
   git add .
   git commit -m "Setup update-docs automation"
   git push
   

🔧 Настройка для разных сценариев

Для команды разработчиков

• PyPI пакет + GitHub Actions для автоматизации
• Pre-commit hooks для локальной проверки

Для личных проектов

• Git Submodule + локальные скрипты
• File watcher для активной разработки документации

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

• Docker контейнер для изоляции
• GitHub Actions с кешированием зависимостей

📋 Checklist для внедрения

• Выбрать способ развертывания (PyPI/Git Submodule/Docker/GitHub Actions)
• Установить update-docs-system в целевом репозитории
• Создать структуру папок (docs/, content/, scripts/)
• Настроить автоматизацию (GitHub Actions/pre-commit/file watcher)
• Запустить первое обновление документации
• Протестировать работу системы
• Обновить .gitignore для исключения временных файлов
• Документировать процесс для команды

🤖 Автогенераторы

Создание автогенератора:

from update_docs.core import register_auto_generator

@register_auto_generator("example_generator.py")
def create_example_docs():
    return "<!-- AUTO-GENERATED -->\n# Generated Documentation"

🔧 Разработка и тестирование

Локальная разработка

# Клонирование репозитория
git clone https://github.com/CoreTwin/docs_repo.git
cd docs_repo

# Установка в режиме разработки
pip install -e .

# Запуск тестов
python -m pytest tests/ -v

# Тестирование внешнего развертывания
python test_external_deployment.py

Структура проекта

update_docs/
├── __init__.py          # Основной модуль
├── cli.py              # Интерфейс командной строки
├── core.py             # Основная логика
└── templates/          # Шаблоны автоматизации
    ├── github_workflow.yml
    ├── pre_commit_hook.sh
    ├── watch_docs.py
    ├── setup_automation.sh
    └── Makefile

content/                # Метаданные документации
├── Content.json        # Структурированные данные о файлах
└── Description_for_agents.md  # Описание для ИИ-систем

scripts/                # Вспомогательные скрипты
├── build_and_publish.sh    # Сборка и публикация пакета
└── setup_automation.sh     # Настройка автоматизации

tests/                  # Тесты
├── test_cli.py         # Тесты CLI
└── test_core.py        # Тесты основной логики

📋 Итоги реализации

✅ Завершенные функции

1. Система Content.json - полная замена toc.json с расширенными метаданными
2. Определение авторства - многоуровневая система классификации файлов
3. Автогенераторы - поддержка создания и защиты автогенерированных файлов
4. Русская навигация - ссылки "Домой" и "Назад" во всех документах
5. Множественные методы развертывания - PyPI, Git Submodule, Docker, GitHub Actions
6. Автоматизация - GitHub Actions, pre-commit hooks, file watcher
7. Persistent file IDs - отслеживание файлов при переименовании
8. Иерархические заголовки - parent_id и excerpt для каждого заголовка
9. Внешнее развертывание - полная изоляция от целевых репозиториев
10. Комплексное тестирование - интеграционные тесты для внешнего развертывания

🔧 Технические особенности

• Обратная совместимость с toc.json системой
• Автоматическое определение типа системы по расширениям файлов
• Защита автогенерированных файлов от случайного редактирования
• Поддержка аннотаций и дополнительной информации к заголовкам
• Интеграция с git для определения авторства по истории коммитов
• PyPI-совместимая структура пакета с шаблонами автоматизации
• Полная изоляция кода от целевых репозиториев

---

📚 Ссылки на документацию:

• Content.json - Структурированные метаданные
• Description for Agents - Описание для ИИ-систем
• Deployment Guide - Подробное руководство по развертыванию