vue-nuxt-docgen

Simple Vue DocGen

Простой генератор документации без зависимостей для проектов на Vue 3, Nuxt и TypeScript. Он парсит JSDoc комментарии, метаданные компонентов Vue (props, slots, emits) и генерирует Markdown файлы.

English Version

Код как Документация (Code as Documentation)

Этот инструмент создан на основе парадигмы Code as Documentation. Вместо того чтобы поддерживать отдельные вики-страницы, которые устаревают, вы пишете документацию прямо в коде.

• Единый источник истины: Ваш код — это и есть документация.
• Готовность к Nuxt: Идеально подходит для документирования слоев, модулей и компонентов Nuxt 3.
• Поддерживаемость: Изменения в коде мгновенно отражаются в сгенерированной документации.

Возможности

• Поддержка Vue 3: Парсит defineProps, defineEmits, slots и описание компонента.
• Поддержка TypeScript: Парсит интерфейсы, типы и обобщенные блоки JSDoc.
• Без зависимостей: Построен с использованием стандартных библиотек Node.js (fs, path).
• Пакетная обработка: Может сканировать несколько директорий и повторять структуру в выходной папке.
• Настраиваемость: Поддерживает шаблоны исключений и кастомные входные/выходные директории.

Установка

npm install vue-nuxt-docgen --save-dev

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

1. Использование через CLI

Один файл:

npx vue-nuxt-docgen src/components/MyComponent.vue docs/MyComponent.md

Пакетный режим (Конфигурация по умолчанию): Запустите в корне вашего проекта, где находится docgen.config.js:

npx vue-nuxt-docgen

Пакетный режим (Кастомный конфиг):

npx vue-nuxt-docgen my-docgen-config.js

2. Конфигурация (docgen.config.js)

Создайте файл docgen.config.js в корне вашего проекта:

export default {
	// Директории для сканирования (массив или строка)
	inputDir: ["src/components", "src/core"],

	// Выходная директория для markdown файлов
	outputDir: "docs/codebase",

	// Расширения файлов для парсинга
	extensions: [".vue", ".ts", ".js"],

	// Директории для игнорирования при сканировании
	excludeDir: ["node_modules", ".git", "dist"],

	// Шаблоны файлов для исключения (поддерживает простые wildcard *)
	excludeFiles: ["*.test.ts", "*.spec.ts", "*.stories.ts"],
};

Руководство по документированию

Поддерживаемые теги

Генератор парсит стандартные теги JSDoc. Специальная обработка применяется к следующим тегам:

Любые другие теги (например, @version, @deprecated, @since) выводятся в общем списке "Tags".

Примеры

Смотрите папку examples/ для полных сценариев использования:

Чтобы запустить генерацию примеров локально:

npm run example

Это создаст документацию в папке examples/generated-docs/.

Написание документации для компонентов

Секция скрипта: Используйте JSDoc комментарии в вашем скрипте или <script setup>.

<script setup lang="ts">
/**
 * @displayName MyButton
 * @description Основной компонент кнопки с различными стилями.
 * @author John Doe
 */
interface Props {
	/**
	 * Текст для отображения внутри кнопки.
	 * @default 'Submit'
	 */
	label?: string;
}

defineProps<Props>();
</script>

Секция шаблона: Документируйте слоты используя HTML комментарии непосредственно перед тегом <slot>.

<template>
	<button>
		<!-- @slot Иконка для отображения перед текстом -->
		<slot name="icon"></slot>
	</button>
</template>