@aigne/doc-smith 0.8.12-beta.2 → 0.8.12-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/.aigne/doc-smith/config.yaml +9 -6
  2. package/.aigne/doc-smith/output/structure-plan.json +123 -109
  3. package/.aigne/doc-smith/upload-cache.yaml +48 -0
  4. package/.github/workflows/publish-docs.yml +4 -7
  5. package/.release-please-manifest.json +1 -1
  6. package/CHANGELOG.md +20 -0
  7. package/agents/clear/choose-contents.mjs +22 -5
  8. package/agents/clear/clear-auth-tokens.mjs +2 -4
  9. package/agents/clear/clear-deployment-config.mjs +49 -0
  10. package/agents/clear/clear-document-config.mjs +2 -5
  11. package/agents/clear/clear-document-structure.mjs +2 -6
  12. package/agents/clear/clear-generated-docs.mjs +0 -1
  13. package/agents/generate/check-need-generate-structure.mjs +15 -60
  14. package/agents/generate/document-structure-tools/generate-sub-structure.mjs +131 -0
  15. package/agents/generate/generate-structure-without-tools.yaml +65 -0
  16. package/agents/generate/generate-structure.yaml +7 -1
  17. package/agents/generate/index.yaml +0 -3
  18. package/agents/generate/update-document-structure.yaml +3 -0
  19. package/agents/generate/user-review-document-structure.mjs +7 -5
  20. package/agents/init/index.mjs +15 -15
  21. package/agents/publish/publish-docs.mjs +132 -113
  22. package/agents/translate/index.yaml +1 -1
  23. package/agents/update/batch-generate-document.yaml +1 -1
  24. package/agents/update/batch-update-document.yaml +1 -1
  25. package/agents/update/check-document.mjs +3 -19
  26. package/agents/update/user-review-document.mjs +4 -3
  27. package/agents/utils/load-sources.mjs +54 -151
  28. package/agents/utils/transform-detail-datasources.mjs +14 -18
  29. package/aigne.yaml +2 -0
  30. package/biome.json +1 -1
  31. package/docs/_sidebar.md +13 -15
  32. package/docs/configuration-initial-setup.ja.md +179 -0
  33. package/docs/configuration-initial-setup.md +179 -0
  34. package/docs/configuration-initial-setup.zh-TW.md +179 -0
  35. package/docs/configuration-initial-setup.zh.md +179 -0
  36. package/docs/configuration-managing-preferences.ja.md +100 -0
  37. package/docs/configuration-managing-preferences.md +100 -0
  38. package/docs/configuration-managing-preferences.zh-TW.md +100 -0
  39. package/docs/configuration-managing-preferences.zh.md +100 -0
  40. package/docs/configuration.ja.md +68 -184
  41. package/docs/configuration.md +62 -178
  42. package/docs/configuration.zh-TW.md +70 -186
  43. package/docs/configuration.zh.md +67 -183
  44. package/docs/getting-started.ja.md +46 -78
  45. package/docs/getting-started.md +46 -78
  46. package/docs/getting-started.zh-TW.md +47 -79
  47. package/docs/getting-started.zh.md +47 -79
  48. package/docs/guides-cleaning-up.ja.md +50 -0
  49. package/docs/guides-cleaning-up.md +50 -0
  50. package/docs/guides-cleaning-up.zh-TW.md +50 -0
  51. package/docs/guides-cleaning-up.zh.md +50 -0
  52. package/docs/guides-evaluating-documents.ja.md +66 -0
  53. package/docs/guides-evaluating-documents.md +66 -0
  54. package/docs/guides-evaluating-documents.zh-TW.md +66 -0
  55. package/docs/guides-evaluating-documents.zh.md +66 -0
  56. package/docs/guides-generating-documentation.ja.md +149 -0
  57. package/docs/guides-generating-documentation.md +149 -0
  58. package/docs/guides-generating-documentation.zh-TW.md +149 -0
  59. package/docs/guides-generating-documentation.zh.md +149 -0
  60. package/docs/guides-interactive-chat.ja.md +85 -0
  61. package/docs/guides-interactive-chat.md +85 -0
  62. package/docs/guides-interactive-chat.zh-TW.md +85 -0
  63. package/docs/guides-interactive-chat.zh.md +85 -0
  64. package/docs/guides-managing-history.ja.md +51 -0
  65. package/docs/guides-managing-history.md +51 -0
  66. package/docs/guides-managing-history.zh-TW.md +51 -0
  67. package/docs/guides-managing-history.zh.md +51 -0
  68. package/docs/guides-publishing-your-docs.ja.md +78 -0
  69. package/docs/guides-publishing-your-docs.md +78 -0
  70. package/docs/guides-publishing-your-docs.zh-TW.md +78 -0
  71. package/docs/guides-publishing-your-docs.zh.md +78 -0
  72. package/docs/guides-translating-documentation.ja.md +95 -0
  73. package/docs/guides-translating-documentation.md +95 -0
  74. package/docs/guides-translating-documentation.zh-TW.md +95 -0
  75. package/docs/guides-translating-documentation.zh.md +95 -0
  76. package/docs/guides-updating-documentation.ja.md +77 -0
  77. package/docs/guides-updating-documentation.md +77 -0
  78. package/docs/guides-updating-documentation.zh-TW.md +77 -0
  79. package/docs/guides-updating-documentation.zh.md +77 -0
  80. package/docs/guides.ja.md +32 -0
  81. package/docs/guides.md +32 -0
  82. package/docs/guides.zh-TW.md +32 -0
  83. package/docs/guides.zh.md +32 -0
  84. package/docs/overview.ja.md +39 -60
  85. package/docs/overview.md +39 -60
  86. package/docs/overview.zh-TW.md +39 -60
  87. package/docs/overview.zh.md +39 -60
  88. package/docs/release-notes.ja.md +255 -0
  89. package/docs/release-notes.md +255 -0
  90. package/docs/release-notes.zh-TW.md +255 -0
  91. package/docs/release-notes.zh.md +255 -0
  92. package/package.json +4 -2
  93. package/prompts/common/document/content-rules-core.md +1 -0
  94. package/prompts/common/document-structure/document-structure-rules.md +8 -9
  95. package/prompts/common/document-structure/output-constraints.md +1 -1
  96. package/prompts/structure/document-rules.md +8 -2
  97. package/prompts/structure/generate/system-prompt.md +27 -2
  98. package/prompts/structure/generate/user-prompt.md +18 -0
  99. package/prompts/structure/update/system-prompt.md +12 -0
  100. package/prompts/structure/update/user-prompt.md +3 -0
  101. package/tests/agents/clear/choose-contents.test.mjs +8 -4
  102. package/tests/agents/generate/check-need-generate-structure.test.mjs +53 -63
  103. package/tests/agents/generate/document-structure-tools/generate-sub-structure.test.mjs +277 -0
  104. package/tests/agents/init/init.test.mjs +18 -18
  105. package/tests/agents/publish/publish-docs.test.mjs +79 -0
  106. package/tests/agents/update/check-document.test.mjs +7 -67
  107. package/tests/agents/utils/load-sources.test.mjs +90 -90
  108. package/tests/agents/utils/transform-detail-datasources.test.mjs +153 -196
  109. package/tests/utils/file-utils.test.mjs +309 -1
  110. package/utils/auth-utils.mjs +12 -5
  111. package/utils/constants/index.mjs +5 -2
  112. package/utils/deploy.mjs +2 -2
  113. package/utils/file-utils.mjs +315 -0
  114. package/utils/utils.mjs +89 -50
  115. package/docs/advanced-how-it-works.ja.md +0 -101
  116. package/docs/advanced-how-it-works.md +0 -101
  117. package/docs/advanced-how-it-works.zh-TW.md +0 -101
  118. package/docs/advanced-how-it-works.zh.md +0 -101
  119. package/docs/advanced-quality-assurance.ja.md +0 -92
  120. package/docs/advanced-quality-assurance.md +0 -92
  121. package/docs/advanced-quality-assurance.zh-TW.md +0 -92
  122. package/docs/advanced-quality-assurance.zh.md +0 -92
  123. package/docs/advanced.ja.md +0 -20
  124. package/docs/advanced.md +0 -20
  125. package/docs/advanced.zh-TW.md +0 -20
  126. package/docs/advanced.zh.md +0 -20
  127. package/docs/changelog.ja.md +0 -486
  128. package/docs/changelog.md +0 -486
  129. package/docs/changelog.zh-TW.md +0 -486
  130. package/docs/changelog.zh.md +0 -486
  131. package/docs/cli-reference.ja.md +0 -311
  132. package/docs/cli-reference.md +0 -311
  133. package/docs/cli-reference.zh-TW.md +0 -311
  134. package/docs/cli-reference.zh.md +0 -311
  135. package/docs/configuration-interactive-setup.ja.md +0 -138
  136. package/docs/configuration-interactive-setup.md +0 -138
  137. package/docs/configuration-interactive-setup.zh-TW.md +0 -138
  138. package/docs/configuration-interactive-setup.zh.md +0 -138
  139. package/docs/configuration-language-support.ja.md +0 -64
  140. package/docs/configuration-language-support.md +0 -64
  141. package/docs/configuration-language-support.zh-TW.md +0 -64
  142. package/docs/configuration-language-support.zh.md +0 -64
  143. package/docs/configuration-llm-setup.ja.md +0 -56
  144. package/docs/configuration-llm-setup.md +0 -56
  145. package/docs/configuration-llm-setup.zh-TW.md +0 -56
  146. package/docs/configuration-llm-setup.zh.md +0 -56
  147. package/docs/configuration-preferences.ja.md +0 -144
  148. package/docs/configuration-preferences.md +0 -144
  149. package/docs/configuration-preferences.zh-TW.md +0 -144
  150. package/docs/configuration-preferences.zh.md +0 -144
  151. package/docs/features-generate-documentation.ja.md +0 -95
  152. package/docs/features-generate-documentation.md +0 -95
  153. package/docs/features-generate-documentation.zh-TW.md +0 -95
  154. package/docs/features-generate-documentation.zh.md +0 -95
  155. package/docs/features-publish-your-docs.ja.md +0 -130
  156. package/docs/features-publish-your-docs.md +0 -130
  157. package/docs/features-publish-your-docs.zh-TW.md +0 -130
  158. package/docs/features-publish-your-docs.zh.md +0 -130
  159. package/docs/features-translate-documentation.ja.md +0 -90
  160. package/docs/features-translate-documentation.md +0 -90
  161. package/docs/features-translate-documentation.zh-TW.md +0 -90
  162. package/docs/features-translate-documentation.zh.md +0 -90
  163. package/docs/features-update-and-refine.ja.md +0 -142
  164. package/docs/features-update-and-refine.md +0 -142
  165. package/docs/features-update-and-refine.zh-TW.md +0 -143
  166. package/docs/features-update-and-refine.zh.md +0 -142
  167. package/docs/features.ja.md +0 -62
  168. package/docs/features.md +0 -62
  169. package/docs/features.zh-TW.md +0 -62
  170. package/docs/features.zh.md +0 -62
@@ -1,95 +0,0 @@
1
- # 產生文件
2
-
3
- `aigne doc generate` 指令是從原始程式碼建立完整文件集的主要功能。此指令會啟動一個流程,分析您的程式碼庫、規劃邏輯性的文件結構,然後為每個部分產生內容。這是從初始狀態建立文件的標準方法。
4
-
5
- ## 首次產生
6
-
7
- 首先,請導覽至您專案的根目錄並執行以下指令:
8
-
9
- ```bash aigne doc generate icon=lucide:play-circle
10
- aigne doc generate
11
- ```
12
-
13
- ### 自動設定
14
-
15
- 如果您是首次在專案中執行此指令,DocSmith 將偵測到沒有任何設定存在。然後,它會自動啟動一個互動式設定精靈,引導您完成所需的設定步驟。此過程可確保在開始產生文件之前,有一個有效的設定。
16
-
17
- ![執行 generate 指令,智慧執行初始化](../assets/screenshots/doc-generate.png)
18
-
19
- 系統會提示您回答一系列問題,以定義文件的關鍵面向,包括:
20
-
21
- * 文件產生規則與風格
22
- * 目標受眾
23
- * 主要語言及任何其他翻譯語言
24
- * 原始程式碼輸入與文件輸出路徑
25
-
26
- ![回答問題以完成專案設定](../assets/screenshots/doc-complete-setup.png)
27
-
28
- 設定完成後,DocSmith 會繼續進行文件產生。
29
-
30
- ![執行結構規劃並產生文件](../assets/screenshots/doc-generate-docs.png)
31
-
32
- 成功完成後,新建立的文件將可在設定時指定的輸出目錄中找到。
33
-
34
- ![文件成功產生](../assets/screenshots/doc-generated-successfully.png)
35
-
36
- ## 產生流程
37
-
38
- `generate` 指令會執行一個自動化的多步驟工作流程。流程概述如下:
39
-
40
- ```d2
41
- direction: down
42
-
43
- User: {
44
- shape: c4-person
45
- }
46
-
47
- AIGNE-CLI: {
48
- label: "AIGNE CLI"
49
-
50
- config-check: {
51
- label: "設定檔是否存在?"
52
- shape: diamond
53
- }
54
-
55
- interactive-setup: {
56
- label: "互動式設定精靈"
57
- }
58
-
59
- generation-process: {
60
- label: "3. 產生流程"
61
-
62
- analyze-code: "分析程式碼"
63
- plan-structure: "規劃結構"
64
- generate-content: "產生內容"
65
-
66
- analyze-code -> plan-structure -> generate-content
67
- }
68
-
69
- output: {
70
- label: "輸出目錄"
71
- }
72
- }
73
-
74
- User -> AIGNE-CLI.config-check: "'aigne doc generate'"
75
- AIGNE-CLI.config-check -> AIGNE-CLI.interactive-setup: "[否] 2. 啟動設定"
76
- AIGNE-CLI.interactive-setup -> AIGNE-CLI.generation-process: "建立設定檔"
77
- AIGNE-CLI.config-check -> AIGNE-CLI.generation-process: "[是]"
78
- AIGNE-CLI.generation-process -> AIGNE-CLI.output: "4. 寫入文件"
79
- ```
80
-
81
- ## 指令選項
82
-
83
- 預設的 `generate` 指令足以應付大多數使用情境。然而,有幾個選項可用於修改其行為,這對於強制完整重新產生或完善文件結構非常有用。
84
-
85
- | 選項 | 描述 | 範例 |
86
- | :------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- |
87
- | `--forceRegenerate` | 刪除所有現有文件並從頭開始重新產生。在對原始程式碼或設定進行重大變更後使用此選項。 | `aigne doc generate --forceRegenerate` |
88
- | `--feedback` | 提供高層次的回饋以完善整體文件結構,例如新增、移除或重組章節。 | `aigne doc generate --feedback "Add an API Reference"` |
89
- | `--model` | 指定從 AIGNE Hub 使用特定的大型語言模型來產生內容,讓您可以在不同模型之間切換。 | `aigne doc generate --model openai:gpt-4o` |
90
-
91
- ## 下一步是什麼?
92
-
93
- 產生初始文件後,您的專案將會持續演進。為了讓您的文件與程式碼保持同步,您需要執行更新。下一節將說明如何根據新的需求或程式碼修改進行針對性變更並重新產生特定檔案。
94
-
95
- <x-card data-title="更新與完善" data-icon="lucide:file-edit" data-href="/features/update-and-refine">學習如何在程式碼變更時更新文件,或使用回饋進行特定改進。</x-card>
@@ -1,95 +0,0 @@
1
- # 生成文档
2
-
3
- `aigne doc generate` 命令是用于从源代码创建完整文档集的主要功能。该命令会启动一个流程,分析您的代码库,规划逻辑化的文档结构,然后为每个部分生成内容。这是从初始状态创建文档的标准方法。
4
-
5
- ## 首次生成
6
-
7
- 首先,请导航到您项目的根目录并运行以下命令:
8
-
9
- ```bash aigne doc generate icon=lucide:play-circle
10
- aigne doc generate
11
- ```
12
-
13
- ### 自动配置
14
-
15
- 如果您是首次在项目中运行此命令,DocSmith 将检测到尚不存在任何配置。随后,它将自动启动一个交互式设置向导,引导您完成所需的设置步骤。此过程可确保在生成开始前已准备好有效的配置。
16
-
17
- ![运行 generate 命令,智能执行初始化](../assets/screenshots/doc-generate.png)
18
-
19
- 系统将提示您回答一系列问题,以定义文档的关键方面,包括:
20
-
21
- * 文档生成规则和风格
22
- * 目标受众
23
- * 主要语言及任何其他翻译语言
24
- * 源代码输入和文档输出路径
25
-
26
- ![回答问题以完成项目设置](../assets/screenshots/doc-complete-setup.png)
27
-
28
- 配置完成后,DocSmith 将继续进行文档生成。
29
-
30
- ![执行结构规划并生成文档](../assets/screenshots/doc-generate-docs.png)
31
-
32
- 成功完成后,新创建的文档将位于设置期间指定的输出目录中。
33
-
34
- ![文档生成成功](../assets/screenshots/doc-generated-successfully.png)
35
-
36
- ## 生成过程
37
-
38
- `generate` 命令执行一个自动化的多步骤工作流。该过程概述如下:
39
-
40
- ```d2
41
- direction: down
42
-
43
- User: {
44
- shape: c4-person
45
- }
46
-
47
- AIGNE-CLI: {
48
- label: "AIGNE CLI"
49
-
50
- config-check: {
51
- label: "配置文件是否存在?"
52
- shape: diamond
53
- }
54
-
55
- interactive-setup: {
56
- label: "交互式设置向导"
57
- }
58
-
59
- generation-process: {
60
- label: "3. 生成过程"
61
-
62
- analyze-code: "分析代码"
63
- plan-structure: "规划结构"
64
- generate-content: "生成内容"
65
-
66
- analyze-code -> plan-structure -> generate-content
67
- }
68
-
69
- output: {
70
- label: "输出目录"
71
- }
72
- }
73
-
74
- User -> AIGNE-CLI.config-check: "'aigne doc generate'"
75
- AIGNE-CLI.config-check -> AIGNE-CLI.interactive-setup: "[否] 2. 启动设置"
76
- AIGNE-CLI.interactive-setup -> AIGNE-CLI.generation-process: "创建配置文件"
77
- AIGNE-CLI.config-check -> AIGNE-CLI.generation-process: "[是]"
78
- AIGNE-CLI.generation-process -> AIGNE-CLI.output: "4. 编写文档"
79
- ```
80
-
81
- ## 命令选项
82
-
83
- 默认的 `generate` 命令足以满足大多数使用场景。但是,有几个选项可用于修改其行为,这对于强制完全重新生成或优化文档结构非常有用。
84
-
85
- | 选项 | 描述 | 示例 |
86
- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- |
87
- | `--forceRegenerate` | 删除所有现有文档并从头开始重新生成。在对源代码或配置进行重大更改后使用此选项。 | `aigne doc generate --forceRegenerate` |
88
- | `--feedback` | 提供高层反馈以优化整体文档结构,例如添加、删除或重组部分。 | `aigne doc generate --feedback "添加 API 参考"` |
89
- | `--model` | 指定 AIGNE Hub 中的特定大型语言模型用于内容生成,允许您在不同模型之间切换。 | `aigne doc generate --model openai:gpt-4o` |
90
-
91
- ## 接下来做什么?
92
-
93
- 生成初始文档后,您的项目将继续发展。为了使您的文档与代码保持同步,您需要执行更新。下一节将解释如何根据新需求或代码修改进行有针对性的更改并重新生成特定文件。
94
-
95
- <x-card data-title="更新和优化" data-icon="lucide:file-edit" data-href="/features/update-and-refine">了解如何在代码更改时更新文档,或使用反馈进行特定改进。</x-card>
@@ -1,130 +0,0 @@
1
- # ドキュメントを公開する
2
-
3
- ドキュメントを生成した後、`aigne doc publish` コマンドはファイルをアップロードし、共有可能なリンクを通じてアクセス可能にします。このガイドでは、公式の AIGNE プラットフォームまたは自己ホスト型のインスタンスにドキュメントを公開するためのステップバイステップのプロセスを提供します。
4
-
5
- ## 公開プロセス
6
-
7
- `aigne doc publish` コマンドは対話型のワークフローを開始します。特定の宛先に初めて公開する場合、CLI はブラウザを開き、一度限りの認証プロセスを案内します。その後の公開では、`~/.aigne/doc-smith-connected.yaml` に保存されている認証情報が使用されます。
8
-
9
- ```d2 公開ワークフロー icon=lucide:upload-cloud
10
- shape: sequence_diagram
11
-
12
- User: {
13
- label: "開発者 / CI-CD"
14
- shape: c4-person
15
- }
16
-
17
- CLI: {
18
- label: "CLI\n(aigne doc publish)"
19
- }
20
-
21
- Local-Config: {
22
- label: "ローカル設定\n(~/.aigne/...)"
23
- shape: cylinder
24
- }
25
-
26
- Browser
27
-
28
- Platform: {
29
- label: "プラットフォーム\n(公式または自己ホスト型)"
30
- }
31
-
32
- User -> CLI: "コマンドを実行"
33
-
34
- alt "対話モード" {
35
- CLI -> Local-Config: "認証情報を確認"
36
- opt "認証情報が見つからない (初回)" {
37
- CLI -> User: "プラットフォームの選択を促す"
38
- User -> CLI: "プラットフォームを選択"
39
- CLI -> Browser: "認証 URL を開く"
40
- User -> Browser: "ログイン & 承認"
41
- Browser -> Platform: "トークンを要求"
42
- Platform -> Browser: "トークンを返す"
43
- Browser -> CLI: "トークンを CLI に送信"
44
- CLI -> Local-Config: "認証情報を保存"
45
- }
46
- CLI -> Platform: "ドキュメントをアップロード"
47
- Platform -> CLI: "成功を確認"
48
- CLI -> User: "成功メッセージを表示"
49
- }
50
-
51
- alt "CI/CD モード" {
52
- note over CLI: "ENV VAR からトークンを読み取る"
53
- CLI -> Platform: "ドキュメントをアップロード"
54
- Platform -> CLI: "成功を確認"
55
- CLI -> User: "成功ステータスを返す"
56
- }
57
- ```
58
-
59
- ## 公開オプション
60
-
61
- ドキュメントをホストするために、2つの主要な宛先から選択できます。
62
-
63
- <x-cards data-columns="2">
64
- <x-card data-title="公式プラットフォーム" data-icon="lucide:globe">
65
- AIGNE が運営するサービスである docsmith.aigne.io に公開します。これは、オープンソースプロジェクトやドキュメントを迅速に公開共有するための簡単なオプションです。
66
- </x-card>
67
- <x-card data-title="自己ホスト型インスタンス" data-icon="lucide:server">
68
- ブランディング、アクセス、データプライバシーを完全に制御するために、独自の Discuss Kit インスタンスに公開します。これは、内部またはプライベートなドキュメントに推奨されるオプションです。公式ドキュメントにある指示に従って、独自の Discuss Kit インスタンスを実行できます。
69
- </x-card>
70
- </x-cards>
71
-
72
- ## ステップバイステップガイド
73
-
74
- 以下の手順に従ってドキュメントを公開してください。
75
-
76
- ### 1. 公開コマンドを実行する
77
-
78
- プロジェクトのルートディレクトリに移動し、次のコマンドを実行します。
79
-
80
- ```bash Terminal icon=lucide:terminal
81
- aigne doc publish
82
- ```
83
-
84
- ### 2. プラットフォームを選択する
85
-
86
- 初めて公開する場合、宛先を選択するよう求められます。要件に合ったオプションを選択してください。
87
-
88
- ![公式プラットフォームまたは自己ホスト型プラットフォームにドキュメントを公開する](../assets/screenshots/doc-publish.png)
89
-
90
- 自己ホスト型のインスタンスを選択した場合、その URL を入力するよう求められます。
91
-
92
- ### 3. アカウントを認証する
93
-
94
- 最初の接続では、ブラウザウィンドウが自動的に開き、ログインして CLI を承認します。このステップはプラットフォームごとに一度だけ必要です。アクセストークンは将来の使用のためにローカルに保存されます。
95
-
96
- ### 4. 確認
97
-
98
- アップロードが完了すると、ターミナルに成功メッセージが表示され、ドキュメントが公開されたことを確認します。
99
-
100
- ```
101
- ✅ Documentation Published Successfully!
102
- ```
103
-
104
- ## CI/CD 環境での公開
105
-
106
- CI/CD パイプラインのような自動化されたワークフローで公開コマンドを使用するには、引数と環境変数を通じて必要な情報を提供することで、対話型のプロンプトをバイパスできます。
107
-
108
- | 方法 | 名前 | 説明 |
109
- |---|---|---|
110
- | **引数** | `--appUrl` | Discuss Kit インスタンスの URL を指定します。 |
111
- | **環境変数** | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | 対話型のログインプロセスをスキップするためのアクセストークンを提供します。 |
112
-
113
- 以下は、CI/CD スクリプトに適した非対話型の公開コマンドの例です。
114
-
115
- ```bash CI/CD の例 icon=lucide:workflow
116
- export DOC_DISCUSS_KIT_ACCESS_TOKEN="your_access_token_here"
117
- aigne doc publish --appUrl https://docs.mycompany.com
118
- ```
119
-
120
- ## トラブルシューティング
121
-
122
- 公開プロセス中に問題が発生した場合、それは以下の一般的な問題のいずれかが原因である可能性があります。
123
-
124
- - **接続エラー**: CLI は `Unable to connect to: <URL>` のようなエラーメッセージを返すことがあります。これは、ネットワークの問題、サーバーが一時的に利用できない、または URL が間違っていることが原因である可能性があります。URL が正しく、サーバーに到達可能であることを確認してください。
125
-
126
- - **無効なウェブサイト URL**: コマンドは `The provided URL is not a valid website on ArcBlock platform` というメッセージで失敗することがあります。宛先 URL は ArcBlock プラットフォーム上に構築されたウェブサイトでなければなりません。ドキュメントをホストするには、独自の Discuss Kit インスタンスを実行できます。
127
-
128
- - **必要なコンポーネントの欠落**: `This website does not have required components for publishing` というエラーは、宛先のウェブサイトに Discuss Kit コンポーネントがインストールされていないことを示します。サイトに必要なコンポーネントを追加するには、Discuss Kit のドキュメントを参照してください。
129
-
130
- コマンドとオプションの完全なリストについては、[CLI コマンドリファレンス](./cli-reference.md) を参照してください。
@@ -1,130 +0,0 @@
1
- # Publish Your Docs
2
-
3
- After generating your documentation, the `aigne doc publish` command uploads your files and makes them accessible via a shareable link. This guide provides a step-by-step process for publishing your documentation to either the official AIGNE platform or a self-hosted instance.
4
-
5
- ## The Publishing Process
6
-
7
- The `aigne doc publish` command initiates an interactive workflow. The first time you publish to a specific destination, the CLI will open a browser to guide you through a one-time authentication process. For subsequent publishes, it will use the saved credentials stored in `~/.aigne/doc-smith-connected.yaml`.
8
-
9
- ```d2 The Publishing Workflow icon=lucide:upload-cloud
10
- shape: sequence_diagram
11
-
12
- User: {
13
- label: "Developer / CI-CD"
14
- shape: c4-person
15
- }
16
-
17
- CLI: {
18
- label: "CLI\n(aigne doc publish)"
19
- }
20
-
21
- Local-Config: {
22
- label: "Local Config\n(~/.aigne/...)"
23
- shape: cylinder
24
- }
25
-
26
- Browser
27
-
28
- Platform: {
29
- label: "Platform\n(Official or Self-Hosted)"
30
- }
31
-
32
- User -> CLI: "Run command"
33
-
34
- alt "Interactive Mode" {
35
- CLI -> Local-Config: "Check for credentials"
36
- opt "Credentials not found (First time)" {
37
- CLI -> User: "Prompt to choose platform"
38
- User -> CLI: "Platform selected"
39
- CLI -> Browser: "Open auth URL"
40
- User -> Browser: "Login & Authorize"
41
- Browser -> Platform: "Request token"
42
- Platform -> Browser: "Return token"
43
- Browser -> CLI: "Send token to CLI"
44
- CLI -> Local-Config: "Save credentials"
45
- }
46
- CLI -> Platform: "Upload documentation"
47
- Platform -> CLI: "Confirm success"
48
- CLI -> User: "Display success message"
49
- }
50
-
51
- alt "CI/CD Mode" {
52
- note over CLI: "Reads token from ENV VAR"
53
- CLI -> Platform: "Upload documentation"
54
- Platform -> CLI: "Confirm success"
55
- CLI -> User: "Return success status"
56
- }
57
- ```
58
-
59
- ## Publishing Options
60
-
61
- You can choose between two primary destinations for hosting your documentation:
62
-
63
- <x-cards data-columns="2">
64
- <x-card data-title="Official Platform" data-icon="lucide:globe">
65
- Publish to docsmith.aigne.io, a service operated by AIGNE. This is a straightforward option for open-source projects or for quickly sharing your documentation publicly.
66
- </x-card>
67
- <x-card data-title="Self-Hosted Instance" data-icon="lucide:server">
68
- Publish to your own Discuss Kit instance for complete control over branding, access, and data privacy. This is the recommended option for internal or private documentation. You can run your own Discuss Kit instance by following the instructions available at the official documentation.
69
- </x-card>
70
- </x-cards>
71
-
72
- ## Step-by-Step Guide
73
-
74
- Follow these steps to publish your documentation.
75
-
76
- ### 1. Run the Publish Command
77
-
78
- Navigate to your project's root directory and execute the following command:
79
-
80
- ```bash Terminal icon=lucide:terminal
81
- aigne doc publish
82
- ```
83
-
84
- ### 2. Choose Your Platform
85
-
86
- If this is your first time publishing, you will be prompted to select a destination. Choose the option that fits your requirements.
87
-
88
- ![Publish documentation to the official platform or a self-hosted platform](../assets/screenshots/doc-publish.png)
89
-
90
- If you select a self-hosted instance, you will be asked to enter its URL.
91
-
92
- ### 3. Authenticate Your Account
93
-
94
- For the initial connection, a browser window will open automatically for you to log in and authorize the CLI. This step is only required once per platform. The access token is saved locally for future use.
95
-
96
- ### 4. Confirmation
97
-
98
- Once the upload is complete, a success message will appear in your terminal, confirming that the documentation is live.
99
-
100
- ```
101
- ✅ Documentation Published Successfully!
102
- ```
103
-
104
- ## Publishing in CI/CD Environments
105
-
106
- To use the publish command in automated workflows like CI/CD pipelines, you can bypass the interactive prompts by providing the necessary information through arguments and environment variables.
107
-
108
- | Method | Name | Description |
109
- |---|---|---|
110
- | **Argument** | `--appUrl` | Specifies the URL of your Discuss Kit instance. |
111
- | **Env Var** | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | Provides the access token to skip the interactive login process. |
112
-
113
- Here is an example of a non-interactive publish command suitable for a CI/CD script:
114
-
115
- ```bash CI/CD Example icon=lucide:workflow
116
- export DOC_DISCUSS_KIT_ACCESS_TOKEN="your_access_token_here"
117
- aigne doc publish --appUrl https://docs.mycompany.com
118
- ```
119
-
120
- ## Troubleshooting
121
-
122
- If you encounter an issue during the publishing process, it may be due to one of the following common problems.
123
-
124
- - **Connection Error**: The CLI may return an error message like `Unable to connect to: <URL>`. This can be caused by network issues, a server that is temporarily unavailable, or an incorrect URL. Verify that the URL is correct and the server is reachable.
125
-
126
- - **Invalid Website URL**: The command may fail with the message `The provided URL is not a valid website on ArcBlock platform`. The destination URL must be a website built on the ArcBlock platform. To host your documentation, you can run your own instance of Discuss Kit.
127
-
128
- - **Missing Required Components**: An error stating `This website does not have required components for publishing` indicates that the destination website does not have the Discuss Kit component installed. Please refer to the Discuss Kit documentation to add the necessary component to your site.
129
-
130
- For a complete list of commands and options, see the [CLI Command Reference](./cli-reference.md).
@@ -1,130 +0,0 @@
1
- # 發佈您的文件
2
-
3
- 在產生您的文件後,`aigne doc publish` 指令會上傳您的檔案,並透過一個可分享的連結讓它們可以被存取。本指南提供了將您的文件發佈到 AIGNE 官方平台或自架實例的逐步流程。
4
-
5
- ## 發佈流程
6
-
7
- `aigne doc publish` 指令會啟動一個互動式工作流程。當您第一次發佈到特定目的地時,CLI 會開啟一個瀏覽器來引導您完成一次性的身份驗證過程。對於後續的發佈,它將使用儲存在 `~/.aigne/doc-smith-connected.yaml` 中的已存認證資訊。
8
-
9
- ```d2 The Publishing Workflow icon=lucide:upload-cloud
10
- shape: sequence_diagram
11
-
12
- User: {
13
- label: "開發者 / CI-CD"
14
- shape: c4-person
15
- }
16
-
17
- CLI: {
18
- label: "CLI\n(aigne doc publish)"
19
- }
20
-
21
- Local-Config: {
22
- label: "本機設定\n(~/.aigne/...)"
23
- shape: cylinder
24
- }
25
-
26
- Browser
27
-
28
- Platform: {
29
- label: "平台\n(官方或自架)"
30
- }
31
-
32
- User -> CLI: "執行指令"
33
-
34
- alt "互動模式" {
35
- CLI -> Local-Config: "檢查認證資訊"
36
- opt "未找到認證資訊 (首次)" {
37
- CLI -> User: "提示選擇平台"
38
- User -> CLI: "已選擇平台"
39
- CLI -> Browser: "開啟驗證 URL"
40
- User -> Browser: "登入並授權"
41
- Browser -> Platform: "請求權杖"
42
- Platform -> Browser: "返回權杖"
43
- Browser -> CLI: "將權杖傳送至 CLI"
44
- CLI -> Local-Config: "儲存認證資訊"
45
- }
46
- CLI -> Platform: "上傳文件"
47
- Platform -> CLI: "確認成功"
48
- CLI -> User: "顯示成功訊息"
49
- }
50
-
51
- alt "CI/CD 模式" {
52
- note over CLI: "從環境變數讀取權杖"
53
- CLI -> Platform: "上傳文件"
54
- Platform -> CLI: "確認成功"
55
- CLI -> User: "返回成功狀態"
56
- }
57
- ```
58
-
59
- ## 發佈選項
60
-
61
- 您可以選擇兩個主要的目的地來託管您的文件:
62
-
63
- <x-cards data-columns="2">
64
- <x-card data-title="官方平台" data-icon="lucide:globe">
65
- 發佈到 docsmith.aigne.io,這是由 AIGNE 營運的服務。對於開源專案或希望快速公開分享文件的使用者來說,這是一個直接的選項。
66
- </x-card>
67
- <x-card data-title="自架實例" data-icon="lucide:server">
68
- 發佈到您自己的 Discuss Kit 實例,以完全控制品牌、存取權限和資料隱私。對於內部或私有文件,這是建議的選項。您可以按照官方文件中提供的說明來運行您自己的 Discuss Kit 實例。
69
- </x-card>
70
- </x-cards>
71
-
72
- ## 逐步指南
73
-
74
- 請按照以下步驟發佈您的文件。
75
-
76
- ### 1. 執行發佈指令
77
-
78
- 導覽至您專案的根目錄並執行以下指令:
79
-
80
- ```bash Terminal icon=lucide:terminal
81
- aigne doc publish
82
- ```
83
-
84
- ### 2. 選擇您的平台
85
-
86
- 如果這是您第一次發佈,系統將提示您選擇一個目的地。請選擇符合您需求的選項。
87
-
88
- ![將文件發佈到官方平台或自架平台](../assets/screenshots/doc-publish.png)
89
-
90
- 如果您選擇自架實例,系統會要求您輸入其 URL。
91
-
92
- ### 3. 驗證您的帳戶
93
-
94
- 對於初次連線,瀏覽器視窗將自動開啟,讓您登入並授權 CLI。此步驟每個平台僅需執行一次。存取權杖會儲存在本機以供未來使用。
95
-
96
- ### 4. 確認
97
-
98
- 上傳完成後,您的終端機中將會出現一條成功訊息,確認文件已上線。
99
-
100
- ```
101
- ✅ 文件發佈成功!
102
- ```
103
-
104
- ## 在 CI/CD 環境中發佈
105
-
106
- 若要在 CI/CD 管線等自動化工作流程中使用發佈指令,您可以透過參數和環境變數提供必要的資訊,以繞過互動式提示。
107
-
108
- | 方法 | 名稱 | 描述 |
109
- |---|---|---|
110
- | **參數** | `--appUrl` | 指定您的 Discuss Kit 實例的 URL。 |
111
- | **環境變數** | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | 提供存取權杖以跳過互動式登入過程。 |
112
-
113
- 以下是一個適用於 CI/CD 指令碼的非互動式發佈指令範例:
114
-
115
- ```bash CI/CD Example icon=lucide:workflow
116
- export DOC_DISCUSS_KIT_ACCESS_TOKEN="your_access_token_here"
117
- aigne doc publish --appUrl https://docs.mycompany.com
118
- ```
119
-
120
- ## 疑難排解
121
-
122
- 如果您在發佈過程中遇到問題,可能是由以下常見問題之一所引起。
123
-
124
- - **連線錯誤**:CLI 可能會返回類似 `Unable to connect to: <URL>` 的錯誤訊息。這可能是由網路問題、伺服器暫時無法使用或 URL 不正確所引起。請確認 URL 是否正確且伺服器是否可連線。
125
-
126
- - **無效的網站 URL**:指令可能會失敗並顯示訊息 `The provided URL is not a valid website on ArcBlock platform`。目的地 URL 必須是建立在 ArcBlock 平台上的網站。若要託管您的文件,您可以運行自己的 Discuss Kit 實例。
127
-
128
- - **缺少必要元件**:出現 `This website does not have required components for publishing` 的錯誤訊息表示目的地網站未安裝 Discuss Kit 元件。請參考 Discuss Kit 文件,將必要的元件新增至您的網站。
129
-
130
- 有關完整的指令和選項列表,請參閱 [CLI 指令參考](./cli-reference.md)。