Diplodoc Extensions API

Diplodoc Extensions API предоставляет механизм для расширения функциональности Diplodoc CLI. Построенный на hook-based системе на основе библиотеки tappable, он позволяет создавать модульные, интегрируемые и расширяемые компоненты.

На базе архитектуры Extensions API построены внутренние модули CLI.

Возможности

• Hook-based Architecture: Система хуков для расширения функциональности на различных этапах процесса сборки документации.
• Type Safety: Полная поддержка TypeScript с подробными определениями типов.
• Modular Design: Создание независимых, переиспользуемых расширений.
• Configuration Support: Гибкая настройка через файлы конфигурации и параметры командной строки.
• Resource Management: Встроенные lifecycle-хуки для правильной инициализации и очистки ресурсов.
• Logging and Debugging: Интегрированная система логирования с несколькими уровнями детализации.

Базовые концепции

Program и Run

В основе архитектуры Diplodoc лежат два ключевых класса:

1. Program — базовый класс для всех команд CLI. Он предоставляет:

   • Систему хуков для расширения функциональности
   • Управление конфигурацией
   • Доступ к логированию
   • Интерфейс для регистрации расширений

2. Run — контекст выполнения команды. Содержит:

   • Доступ к сервисам (TOC, Markdown, Leading и др.)
   • Информацию о текущем состоянии
   • Утилиты для работы с файлами
   • Системы логирования и отладки

Хуки и их использование

Хуки — это основной механизм расширения функциональности. Они позволяют:

• Встраиваться в различные этапы выполнения программы
• Модифицировать поведение сервисов
• Добавлять новую функциональность

Существует два типа хуков:

1. Base Hooks — общие хуки программы:

   export class Extension {
       apply(program: Build) {
           // Получение базовых hooks
           const baseHooks = getBaseHooks(program);
           
           // Hook перед любым запуском
           baseHooks.BeforeAnyRun.tap('MyExtension', (run) => {
               // Инициализация
           });
           
           // Hook после выполнения
           baseHooks.AfterAnyRun.tap('MyExtension', (run) => {
               // Очистка
           });
       }
   }
   

2. Service Hooks — специфичные для каждого сервиса:

   export class Extension {
       apply(program: Build) {
           getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
               // Получение hooks конкретного сервиса
               const tocHooks = getTocHooks(run.toc);
               const markdownHooks = getMarkdownHooks(run.markdown);
               const leadingHooks = getLeadingHooks(run.leading);
               
               // Использование hooks
               tocHooks.Item.tap('MyExtension', (item) => {
                   // Обработка элемента TOC
               });
           });
       }
   }
   

Работа с сервисами

Сервисы — это основные компоненты Diplodoc, отвечающие за различные аспекты обработки документации.
Доступ к сервисам осуществляется через контекст run:

export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // Доступ к сервисам
            const {toc, markdown, leading, meta, vars} = run;
            
            // Получение hooks сервисов
            const tocHooks = getTocHooks(toc);
            const markdownHooks = getMarkdownHooks(markdown);
            const leadingHooks = getLeadingHooks(leading);
            const metaHooks = getMetaHooks(meta);
            const varsHooks = getVarsHooks(vars);
        });
    }
}

Подробное описание каждого сервиса:

• TOC Service — управление структурой документации.
• Leading Service — обработка разводящих страниц.
• Markdown Service — трансформация markdown-контента.
• Meta Service — работа с метаданными документации.
• Vars Service — управление переменными и шаблонами.
• VCS Service — работа с системой контроля версий.
• Search Service — организация поиска по документации.
• Logger Service — управление логгированием.

Когда использовать расширения

Расширения особенно полезны, когда вам нужно:

1. Добавить новые параметры командной строки в Diplodoc CLI.
2. Модифицировать или улучшить процесс сборки документации.
3. Добавить поддержку новых типов файлов или методов обработки.
4. Интегрироваться с внешними сервисами или API.
5. Добавить пользовательские шаги валидации или трансформации документов.

Типы расширений

Diplodoc поддерживает несколько типов расширений, каждый из которых предназначен для решения определенных задач:

1. Command Extensions

Этот тип расширений позволяет модифицировать CLI-интерфейс Diplodoc. Используйте его, когда нужно:

• добавить новые команды в CLI,
• расширить существующие команды новыми параметрами,
• изменить поведение существующих команд.

В примере ниже показано, как добавить новый параметр к команде:

import {Build} from '@diplodoc/cli';

export class Extension {
    apply(program) {
        if (Build.is(program)) {
           getBaseHooks(program).Command.tap('MyCommand', (command) => {
              command.addOption(new Option('--my-option'));
           }); 
        }
    }
}

2. Processing Extensions

Processing Extensions предназначены для модификации процесса сборки документации. Они особенно полезны, когда вам нужно:

• изменить содержимое или структуру TOC,
• трансформировать markdown-контент,
• добавить пользовательские включатели,
• выполнить валидацию контента во время сборки.

export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyProcessor', (run) => {
            // Получение hooks нужных сервисов
            const tocHooks = getTocHooks(run.toc);
            const markdownHooks = getMarkdownHooks(run.markdown);
            
            // Настройка обработки
            tocHooks.Item.tapPromise('MyProcessor', async (item) => {
                // Обработка элемента TOC
                return item;
            });
            
            markdownHooks.Resolved.tapPromise('MyProcessor', async (content) => {
                // Обработка markdown
                return content;
            });
        });
    }
}

3. Integration Extensions

Integration Extensions обеспечивают взаимодействие Diplodoc с внешними сервисами. Используйте их для:

• загрузки данных из внешних API,
• обогащения документации внешними метаданными,
• синхронизации с другими системами,
• отправки уведомлений или метрик.

Пример расширения:

export class Extension {
    constructor(private apiKey: string) {}
    
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyIntegration', (run) => {
            // Интеграция с внешним API
            getLeadingHooks(run.leading).Resolved.tapPromise('MyIntegration', async (content) => {
                const externalData = await this.fetchExternalData(this.apiKey);
                return {
                    ...content,
                    externalData
                };
            });
        });
    }

    private async fetchExternalData(apiKey: string) {
        // Логика получения данных из внешнего API
    }
}