@aigne/doc-smith 0.7.0 → 0.7.2

package/docs/configuration-llm-setup.md

@@ -0,0 +1,90 @@
+---
+labels: ["Reference"]
+---
+
+# LLM Setup
+
+AIGNE DocSmith leverages Large Language Models (LLMs) to generate high-quality documentation. You can configure DocSmith to use different AI models through two primary methods: the recommended AIGNE Hub service or by providing your own custom API keys.
+
+This guide will walk you through both options.
+
+## Using AIGNE Hub (Recommended)
+
+The most straightforward way to use LLMs with DocSmith is through AIGNE Hub. This approach offers significant advantages:
+
+- **No API Key Required:** You don't need to sign up for separate AI services or manage your own API keys.
+- **Easy Model Switching:** You can switch between different state-of-the-art models from providers like Google, Anthropic, and OpenAI with a simple command-line flag.
+
+To specify a model, use the `--model` flag with the `generate` command. DocSmith will handle the API requests through the AIGNE Hub.
+
+### Examples
+
+Here are some examples of how to generate documentation using different models available via AIGNE Hub:
+
+**Using Google's Gemini 1.5 Flash:**
+```bash
+aigne doc generate --model google:gemini-2.5-flash
+```
+
+**Using Anthropic's Claude 3.5 Sonnet:**
+```bash
+aigne doc generate --model claude:claude-3-5-sonnet
+```
+
+**Using OpenAI's GPT-4o:**
+```bash
+aigne doc generate --model openai:gpt-4o
+```
+
+## Configuring Custom API Keys
+
+If you prefer to use your own API keys for providers like OpenAI or Anthropic, you can configure them using the interactive setup wizard.
+
+Run the `init` command to launch the wizard, which will guide you through setting up your LLM provider and credentials, among other project settings.
+
+```bash
+# Launch the interactive configuration wizard
+aigne doc init
+```
+
+This process ensures your keys are stored correctly for all subsequent documentation generation and update tasks.
+
+## How It Works
+
+The following diagram illustrates how DocSmith processes requests with different LLM configurations.
+
+```d2
+direction: down
+
+User: {
+  shape: person
+  label: "Developer"
+}
+
+CLI: "`aigne doc generate`"
+
+DocSmith: {
+  shape: package
+  "Configuration Check": {
+    "AIGNE Hub (Default)": "No API Key Needed"
+    "Custom Provider": "User API Key Found"
+  }
+}
+
+LLM_Providers: {
+  label: "LLM Providers"
+  shape: cloud
+  "AIGNE Hub": "Manages access to multiple models"
+  "Direct API (e.g., OpenAI)": "Uses custom key"
+}
+
+User -> CLI: "Runs command"
+CLI -> DocSmith: "Initiates process"
+DocSmith."Configuration Check"."AIGNE Hub (Default)" -> LLM_Providers."AIGNE Hub" : "Routes request via Hub"
+DocSmith."Configuration Check"."Custom Provider" -> LLM_Providers."Direct API (e.g., OpenAI)" : "Routes request with user's key"
+
+```
+
+---
+
+With your LLM provider configured, you are ready to customize language settings for your documentation. Learn more in the [Language Support](./configuration-language-support.md) guide.

package/docs/configuration-llm-setup.zh.md

@@ -0,0 +1,90 @@
+---
+labels: ["Reference"]
+---
+
+# LLM 设置
+
+AIGNE DocSmith 利用大型语言模型 (LLMs) 生成高质量的文档。你可以通过两种主要方法配置 DocSmith 以使用不同的 AI 模型：推荐的 AIGNE Hub 服务，或提供你自己的自定义 API 密钥。
+
+本指南将引导你了解这两种选项。
+
+## 使用 AIGNE Hub (推荐)
+
+通过 AIGNE Hub 是将 DocSmith 与 LLMs 结合使用的最直接方法。该方法具有以下显著优势：
+
+- **无需 API 密钥：** 你无需注册单独的 AI 服务或管理自己的 API 密钥。
+- **轻松切换模型：** 你可以通过一个简单的命令行标志，在 Google、Anthropic 和 OpenAI 等提供商提供的不同顶尖模型之间进行切换。
+
+要指定模型，请在 `generate` 命令中使用 `--model` 标志。DocSmith 将通过 AIGNE Hub 处理 API 请求。
+
+### 示例
+
+以下示例展示了如何通过 AIGNE Hub 使用不同的模型生成文档：
+
+**使用 Google 的 Gemini 1.5 Flash：**
+```bash
+aigne doc generate --model google:gemini-2.5-flash
+```
+
+**使用 Anthropic 的 Claude 3.5 Sonnet：**
+```bash
+aigne doc generate --model claude:claude-3-5-sonnet
+```
+
+**使用 OpenAI 的 GPT-4o：**
+```bash
+aigne doc generate --model openai:gpt-4o
+```
+
+## 配置自定义 API 密钥
+
+如果你希望为 OpenAI 或 Anthropic 等提供商使用自己的 API 密钥，可以通过交互式设置向导进行配置。
+
+运行 `init` 命令启动向导，它将指导你完成 LLM 提供商、凭据以及其他项目设置。
+
+```bash
+# 启动交互式配置向导
+aigne doc init
+```
+
+该过程可确保你的密钥被正确存储，以便用于所有后续的文档生成和更新任务。
+
+## 工作原理
+
+下图说明了 DocSmith 在不同 LLM 配置下处理请求的流程。
+
+```d2
+direction: down
+
+User: {
+  shape: person
+  label: "开发者"
+}
+
+CLI: "`aigne doc generate`"
+
+DocSmith: {
+  shape: package
+  "配置检查": {
+    "AIGNE Hub (默认)": "无需 API 密钥"
+    "自定义提供商": "找到用户 API 密钥"
+  }
+}
+
+LLM_Providers: {
+  label: "LLM 提供商"
+  shape: cloud
+  "AIGNE Hub": "管理对多个模型的访问"
+  "直接 API (例如 OpenAI)": "使用自定义密钥"
+}
+
+User -> CLI: "运行命令"
+CLI -> DocSmith: "启动流程"
+DocSmith."配置检查"."AIGNE Hub (默认)" -> LLM_Providers."AIGNE Hub" : "通过 Hub 路由请求"
+DocSmith."配置检查"."自定义提供商" -> LLM_Providers."直接 API (例如 OpenAI)" : "使用用户密钥路由请求"
+
+```
+
+---
+
+配置好 LLM 提供商后，你就可以为文档自定义语言设置了。请在 [语言支持](./configuration-language-support.md) 指南中了解更多信息。

package/docs/configuration-preferences.md

@@ -0,0 +1,122 @@
+---
+labels: ["Reference"]
+---
+
+# Managing Preferences
+
+DocSmith is designed to learn from your feedback. When you refine documents and provide corrections, the system can convert that feedback into persistent, reusable rules called "preferences". This ensures that your stylistic choices, structural conventions, and specific instructions are remembered and applied consistently in future operations.
+
+All preferences are stored in a human-readable YAML file located at `.aigne/doc-smith/preferences.yml` in your project root. While you can view this file, it's recommended to manage your preferences using the dedicated `aigne doc prefs` command-line interface.
+
+## How Preferences Are Created
+
+Preferences are automatically generated during the feedback cycle of commands like `aigne doc refine`. The process works as follows:
+
+```d2
+direction: right
+
+User: {
+  shape: person
+}
+
+Refine: "`aigne doc refine` command"
+
+FeedbackRefiner: "Feedback→Rule Converter"
+
+PreferencesFile: "preferences.yml" {
+  shape: document
+}
+
+User -> Refine: "Provide feedback, e.g., 'Don't translate variable names'"
+Refine -> FeedbackRefiner: "Sends feedback for analysis"
+FeedbackRefiner -> PreferencesFile: "Saves new, reusable rule" {
+  style.animated: true
+}
+
+```
+
+1.  **Feedback Input**: You provide natural language feedback during a refinement session.
+2.  **Rule Generation**: An internal agent analyzes your feedback to determine if it represents a reusable policy rather than a one-time fix.
+3.  **Rule Creation**: If deemed reusable, it creates a structured rule with a specific scope (e.g., `document`, `translation`), a unique ID, and the instruction itself.
+4.  **Persistence**: The new rule is saved to the `preferences.yml` file, making it active for future tasks.
+
+## Managing Preferences via CLI
+
+The `aigne doc prefs` command is your primary tool for viewing and managing all saved preferences.
+
+### List All Preferences
+
+To see a formatted list of all your preferences, use the `--list` flag.
+
+```bash
+aigne doc prefs --list
+```
+
+The output provides a clear overview of each rule:
+
+```text
+# User Preferences
+
+**Format explanation:**
+- 🟢 = Active preference, ⚪ = Inactive preference
+- [scope] = Preference scope (global, structure, document, translation)
+- ID = Unique preference identifier
+- Paths = Specific file paths (if applicable)
+
+🟢 [translation] pref_1a2b3c4d
+   Keep code and identifiers unchanged during translation, must not translate them.
+
+⚪ [structure] pref_5e6f7g8h | Paths: overview.md, tutorials.md
+   Add 'Next Steps' section at the end of overview and tutorial documents with 2-3 links within the repository.
+```
+
+- **Status (🟢 / ⚪)**: Shows whether a rule is currently active or inactive.
+- **Scope**: Indicates where the rule applies (e.g., `translation`, `structure`).
+- **ID**: A unique identifier used to manage the rule.
+- **Paths**: If a rule is limited to specific files, they will be listed here.
+
+### Toggle Preference Status
+
+You can activate or deactivate preferences using the `--toggle` flag. This is useful for temporarily disabling a rule without deleting it permanently.
+
+**Interactive Mode**
+
+If you run the command without specifying an ID, an interactive prompt will appear, allowing you to select multiple rules to toggle.
+
+```bash
+aigne doc prefs --toggle
+```
+
+**By ID**
+
+To toggle specific rules, provide their IDs using the `--id` option.
+
+```bash
+aigne doc prefs --toggle --id pref_5e6f7g8h
+```
+
+### Remove Preferences
+
+To permanently delete one or more preferences, use the `--remove` flag.
+
+**Interactive Mode**
+
+Running the command without an ID will launch an interactive selection prompt.
+
+```bash
+aigne doc prefs --remove
+```
+
+**By ID**
+
+To remove a specific rule, pass its ID.
+
+```bash
+aigne doc prefs --remove --id pref_1a2b3c4d
+```
+
+This action is irreversible, so use it with care.
+
+---
+
+By managing your preferences, you can fine-tune DocSmith's behavior over time, making the documentation process increasingly automated and aligned with your project's specific needs. To see how feedback is provided, you can learn more in the [Update and Refine](./features-update-and-refine.md) guide.

package/docs/configuration-preferences.zh.md

@@ -0,0 +1,123 @@
+---
+labels: ["Reference"]
+---
+
+# 管理偏好
+
+DocSmith 旨在通过您的反馈进行学习。当您优化文档并提供更正时，系统可以将这些反馈转化为称为“偏好”的持久、可重用的规则。这确保了您的风格选择、结构约定和具体指令在未来的操作中能够被记住并一致地应用。
+
+所有偏好都存储在项目根目录下名为 `.aigne/doc-smith/preferences.yml` 的人类可读 YAML 文件中。虽然您可以查看此文件，但建议使用专用的 `aigne doc prefs` 命令行界面来管理您的偏好。
+
+## 偏好是如何创建的
+
+偏好在 `aigne doc refine` 等命令的反馈周期中自动生成。其过程如下：
+
+```d2
+direction: right
+
+User: {
+  shape: person
+  label: "用户"
+}
+
+Refine: "`aigne doc refine` 命令"
+
+FeedbackRefiner: "反馈→规则转换器"
+
+PreferencesFile: "preferences.yml" {
+  shape: document
+}
+
+User -> Refine: "提供反馈，例如‘不要翻译变量名’"
+Refine -> FeedbackRefiner: "发送反馈进行分析"
+FeedbackRefiner -> PreferencesFile: "保存新的可重用规则" {
+  style.animated: true
+}
+
+```
+
+1.  **反馈输入**：您在优化会话期间提供自然语言反馈。
+2.  **规则生成**：一个内部 Agent 会分析您的反馈，以确定它代表的是可重用策略还是一次性修复。
+3.  **规则创建**：如果被认为是可重用的，它会创建一个结构化规则，包含特定的作用域（例如，`document`、`translation`）、唯一的 ID 以及指令本身。
+4.  **持久化**：新规则被保存到 `preferences.yml` 文件中，使其在未来的任务中生效。
+
+## 通过 CLI 管理偏好
+
+`aigne doc prefs` 命令是您查看和管理所有已保存偏好的主要工具。
+
+### 列出所有偏好
+
+要查看所有偏好的格式化列表，请使用 `--list` 标志。
+
+```bash
+aigne doc prefs --list
+```
+
+输出清晰地展示了每个规则的概览：
+
+```text
+# 用户偏好
+
+**格式说明：**
+- 🟢 = 活动偏好, ⚪ = 非活动偏好
+- [scope] = 偏好作用域 (global, structure, document, translation)
+- ID = 唯一偏好标识符
+- Paths = 特定文件路径 (如果适用)
+
+🟢 [translation] pref_1a2b3c4d
+   在翻译期间保持代码和标识符不变，不得翻译它们。
+
+⚪ [structure] pref_5e6f7g8h | 路径：overview.md, tutorials.md
+   在概述和教程文档末尾添加“后续步骤”部分，并附上 2-3 个仓库内的链接。
+```
+
+- **状态 (🟢 / ⚪)**：显示规则当前是活动还是非活动状态。
+- **作用域**：指明规则的应用范围（例如，`translation`、`structure`）。
+- **ID**：用于管理规则的唯一标识符。
+- **路径**：如果规则仅限于特定文件，这些文件将在此处列出。
+
+### 切换偏好状态
+
+您可以使用 `--toggle` 标志来激活或停用偏好。这在临时禁用某个规则而不想永久删除它时非常有用。
+
+**交互模式**
+
+如果您在运行命令时未指定 ID，将会出现一个交互式提示，允许您选择多个规则进行切换。
+
+```bash
+aigne doc prefs --toggle
+```
+
+**按 ID 操作**
+
+要切换特定规则的状态，请使用 `--id` 选项提供其 ID。
+
+```bash
+aigne doc prefs --toggle --id pref_5e6f7g8h
+```
+
+### 删除偏好
+
+要永久删除一个或多个偏好，请使用 `--remove` 标志。
+
+**交互模式**
+
+在不带 ID 的情况下运行该命令将启动一个交互式选择提示。
+
+```bash
+aigne doc prefs --remove
+```
+
+**按 ID 操作**
+
+要删除特定规则，请传递其 ID。
+
+```bash
+aigne doc prefs --remove --id pref_1a2b3c4d
+```
+
+此操作不可逆，请谨慎使用。
+
+---
+
+通过管理您的偏好，您可以随着时间的推移微调 DocSmith 的行为，使文档处理过程越来越自动化，并与您项目的特定需求保持一致。要了解如何提供反馈，您可以在 [更新与优化](./features-update-and-refine.md) 指南中了解更多信息。

package/docs/configuration.md

@@ -0,0 +1,173 @@
+---
+labels: ["Reference"]
+---
+
+# Configuration Guide
+
+AIGNE DocSmith's behavior is controlled by a single, powerful configuration file: `config.yaml`. This file, located in the `.aigne/doc-smith` directory of your project, allows you to customize every aspect of the documentation generation process—from the intended audience and style to language support and file structure.
+
+This guide provides a detailed reference for all available settings. While you can edit this file manually at any time, we recommend using the [Interactive Setup](./configuration-interactive-setup.md) wizard for your initial configuration.
+
+## Configuration Overview
+
+DocSmith offers a flexible configuration system to match your project's unique needs. You can define the goals of your documentation, specify your audience, set up AI models, and manage multiple languages. Explore the key areas of configuration below.
+
+<x-cards data-columns="2">
+  <x-card data-title="Interactive Setup" data-href="/configuration/interactive-setup" data-icon="lucide:wand-2">
+    Learn how to use the `aigne doc init` command to run a guided wizard that creates your initial configuration file effortlessly.
+  </x-card>
+  <x-card data-title="LLM Setup" data-href="/configuration/llm-setup" data-icon="lucide:brain-circuit">
+    Configure different Large Language Models, including using the integrated AIGNE Hub for key-free access to popular models.
+  </x-card>
+  <x-card data-title="Language Support" data-href="/configuration/language-support" data-icon="lucide:languages">
+    Set your primary documentation language and choose from over 12 supported languages for automatic translation.
+  </x-card>
+  <x-card data-title="Managing Preferences" data-href="/configuration/preferences" data-icon="lucide:sliders-horizontal">
+    Understand how DocSmith learns from your feedback to create persistent rules and how to manage them.
+  </x-card>
+</x-cards>
+
+## Parameter Reference
+
+The `config.yaml` file contains several key sections that define how your documentation is generated. Below is a comprehensive breakdown of each parameter.
+
+### Project Information
+
+These settings are used for display purposes when you publish your documentation.
+
+```yaml
+# Project information for documentation publishing
+projectName: AIGNE DocSmith
+projectDesc: An AI-driven documentation generation tool.
+projectLogo: https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png
+```
+
+- `projectName`: The name of your project.
+- `projectDesc`: A short description of your project.
+- `projectLogo`: A URL to your project's logo.
+
+### Documentation Style
+
+These parameters define the purpose, audience, and overall tone of your documentation.
+
+#### `documentPurpose`
+
+Defines the primary goal for your readers. You can select multiple purposes.
+
+| Key | Name | Description |
+|---|---|---|
+| `getStarted` | Get started quickly | Help new users go from zero to working in <30 minutes. |
+| `completeTasks` | Complete specific tasks | Guide users through common workflows and use cases. |
+| `findAnswers` | Find answers fast | Provide searchable reference for all features and APIs. |
+| `understandSystem` | Understand the system | Explain how it works, why design decisions were made. |
+| `solveProblems` | Troubleshoot common issues | Help users troubleshoot and fix issues. |
+| `mixedPurpose` | Serve multiple purposes | Comprehensive documentation covering multiple needs. |
+
+**Example:**
+```yaml
+documentPurpose:
+  - getStarted
+  - findAnswers
+```
+
+#### `targetAudienceTypes`
+
+Specifies the primary audience for the documentation.
+
+| Key | Name | Description |
+|---|---|---|
+| `endUsers` | End users (non-technical) | People who use the product but don't code. |
+| `developers` | Developers integrating your product/API | Engineers adding this to their projects. |
+| `devops` | DevOps / SRE / Infrastructure teams | Teams deploying, monitoring, maintaining systems. |
+| `decisionMakers` | Technical decision makers | Architects, leads evaluating or planning implementation. |
+| `supportTeams` | Support teams | People helping others use the product. |
+| `mixedTechnical` | Mixed technical audience | Developers, DevOps, and technical users. |
+
+**Example:**
+```yaml
+targetAudienceTypes:
+  - developers
+```
+
+#### `readerKnowledgeLevel`
+
+Describes the typical starting knowledge level of your readers.
+
+| Key | Name | Description |
+|---|---|---|
+| `completeBeginners` | Is a total beginner, starting from scratch | New to this domain/technology entirely. |
+| `domainFamiliar` | Has used similar tools before | Knows the problem space, new to this specific solution. |
+| `experiencedUsers` | Is an expert trying to do something specific | Regular users needing reference/advanced topics. |
+| `emergencyTroubleshooting` | Emergency/troubleshooting | Something's broken, need to fix it quickly. |
+| `exploringEvaluating` | Is evaluating this tool against others | Trying to understand if this fits their needs. |
+
+**Example:**
+```yaml
+readerKnowledgeLevel: completeBeginners
+```
+
+#### `documentationDepth`
+
+Controls how comprehensive the documentation should be.
+
+| Key | Name | Description |
+|---|---|---|
+| `essentialOnly` | Essential only | Cover the 80% use cases, keep it concise. |
+| `balancedCoverage` | Balanced coverage | Good depth with practical examples [RECOMMENDED]. |
+| `comprehensive` | Comprehensive | Cover all features, edge cases, and advanced scenarios. |
+| `aiDecide` | Let AI decide | Analyze code complexity and suggest appropriate depth. |
+
+**Example:**
+```yaml
+documentationDepth: balancedCoverage
+```
+
+### Custom Rules & Descriptions
+
+These fields allow for more specific instructions to the AI.
+
+- `rules`: A multi-line string where you can define specific rules and requirements for generation, such as "Always include a 'Prerequisites' section in tutorials."
+- `targetAudience`: A multi-line string to describe your target audience in more detail than the presets allow.
+
+**Example:**
+```yaml
+rules: |
+  - All code examples must be complete and copy-paste ready.
+  - Avoid using technical jargon without explaining it first.
+targetAudience: |
+  Our audience consists of front-end developers who are familiar with JavaScript but may be new to backend concepts. They value clear, practical examples.
+```
+
+### Language and Path Settings
+
+These parameters configure the languages and file locations for your documentation.
+
+- `locale`: The primary language for the documentation (e.g., `en`, `zh`).
+- `translateLanguages`: A list of language codes to translate the documentation into.
+- `glossary`: Path to a Markdown file containing project-specific terms to ensure consistent translations.
+- `docsDir`: The directory where the generated documentation will be saved.
+- `sourcesPath`: A list of source code paths or glob patterns for the AI to analyze.
+
+**Example:**
+```yaml
+# Language settings
+locale: en
+translateLanguages:
+  - zh
+  - ja
+
+# Glossary for consistent terminology
+glossary: "@glossary.md"
+
+# Directory and source path configurations
+docsDir: .aigne/doc-smith/docs  # Directory to save generated documentation
+sourcesPath:  # Source code paths to analyze
+  - ./src
+  - ./README.md
+```
+
+---
+
+With your `config.yaml` file tailored to your project, you're ready to create your documentation. The next step is to run the generation command.
+
+➡️ **Next:** Learn how to [Generate Documentation](./features-generate-documentation.md).