在本文中，我將指導您一步一步建立一個適用於任何專案的動態(tài)文件站點，您可以在其中將文件連接到資料庫以提取和顯示數(shù)據(jù)，確保資訊始終是最新的。我們也將探索如何使用 AWS.

自動化整個流程，從內容產生到雲(yún)端部署

此解決方案包括對圖表和圖表的支援、使用 GitHub Actions 中簡單工作流程的持續(xù)整合 (CI/CD) 以及使用 Terraform 的自動部署。讓我們開始吧！

---

什麼是文檔即程式碼？

文件及其更新是許多開發(fā)軟體的公司的重要流程，通常使用不同的工具進行，其中許多是付費解決方案。

因此，最近出現(xiàn)了“doc as code”的概念。這意味著使用軟體開發(fā)中使用的相同工具和工作流程來管理、版本和部署文件。

這種方法不僅可以更好地追蹤文檔，還可以促進其維護，並確保與軟體開發(fā)中使用的相同最佳實踐保持一致，不僅在程式碼中，而且在文件中。

---

將文件作為程式碼的工具

對於這些網(wǎng)站的開發(fā)，有必要了解一些允許我們實施這種方法的實踐和工具。以下是本教程中要涵蓋的最重要方面的詳細清單。

• ？ Markdown：由於其簡單性以及與版本控制平臺和靜態(tài)站點生成器的集成，是編寫文檔最常用的標記語言。
• ?? Git：Git 允許像程式碼一樣對文件進行版本控制。感謝 Git，記錄了文件中的每一個更改，使團隊能夠追蹤編輯、恢復更改並更有效地協(xié)作。
• ？ Gitflow：此方法提供了一個結構化的工作流程來管理文件的版本和修訂，確保變更在投入生產之前得到批準和測試。 Gitflow 也促進團隊之間的協(xié)作，從而實現(xiàn)安全且有組織的變更管理。
• ?? 雲(yún)端服務：使用 AWS S3、Netlify 或 GitHub Pages 等服務，您可以以較低的成本部署文件。這些服務允許建立快速、安全且易於存取的靜態(tài)網(wǎng)站。
• ？ 靜態(tài)網(wǎng)站產生器：Docusaurus、Jekyll 或 Hugo 等工具將 Markdown 文件轉換為可導航的網(wǎng)站，讓您無需伺服器即可建立豐富且有組織的文件。
• ？ 持續(xù)整合 (CI/CD)：CI/CD 管道（例如 GitHub Actions、GitLab CI 或 Jenkins）可讓您在合併新版本或核準修改時自動部署文件。這可確保文件始終是最新的。

---

文檔即程式碼的優(yōu)點

• ? 一致性和品質：透過使用版本控制和變更審核，文件保持一致且高品質。
• ?? 自動化：CI/CD 工具可實現(xiàn)文件部署的自動化，減少更新時間並最大限度地減少錯誤。
• ？高效協(xié)作：借助 Git 等工具，團隊可以協(xié)作創(chuàng)建和維護文檔，而不會發(fā)生衝突。
• ？簡化維護：維護文件已整合到開發(fā)工作流程中，隨著程式碼的發(fā)展，更新變得更加容易。

---

？ MK文檔

MkDocs 是一個用 ?Python 編寫的靜態(tài)網(wǎng)站產生器，專為文件專案而設計。其目標是簡化使用 Markdown 文件建立文檔，這些文件易於編寫和閱讀。

透過最少的配置，MkDocs 將 Markdown 文件轉換為可導航且結構良好的文件網(wǎng)站，使其成為想要保持文件最新的開發(fā)人員和團隊的理想選擇。

---

?? MkDocs 材料

MkDocs Material 是 MkDocs 的高級主題，遵循 Google 的 Material Design 指南。

？主要特點包括：

• ？ 響應式設計：自動適應任何螢幕尺寸。
• ？ 自訂：輕鬆修改顏色、字體、圖示和標誌以符合您項目的視覺識別。
• ？ 搜尋介面：進階搜尋將結果分組並突出顯示搜尋的術語，幫助使用者找到所需的資訊。
• ? 延遲加載：對搜尋結果實現(xiàn)延遲加載，提高效能並減少加載時間。
• ？ 整合：相容於Google Analytics、Disqus和GitHub，方便流量分析、使用者回饋以及直接連接到專案儲存庫。

---

??美人魚

Mermaid 是一個 JavaScript 函式庫，用於從文字建立圖表。透過與 MkDocs Material 集成，Mermaid 可讓您在文件中產生視覺化效果，例如流程圖、實體關係圖和文件中的其他圖表，而無需外部工具。

---

？動態(tài)頁：Jinja

Jinja 是一個函式庫，允許將 Python 字典中的變數(shù)和資料嵌入到 HTML 中，使網(wǎng)頁動態(tài)化。該程式庫通常用於產生動態(tài) HTML 和發(fā)送個人化電子郵件。

---

？多庫龍概述

Docusaurus 是 Meta 於 2007 年開發(fā)的開源項目，它以快速且有效率的方式簡化了文件網(wǎng)站的建立、部署和維護。它允許使用 Markdown 和 MDX 來編寫內容，而其基於 React 的核心可以完全自訂樣式，以滿足專案的特定需求。

此外，Docusaurus 透過 @docusaurus/theme-mermaid 插件支援 Mermaid，從而可以直接在文件中包含圖表和圖表。

---

？圖表即程式碼

圖表即程式碼是一種允許您透過程式碼而不是使用傳統(tǒng)圖形工具來建立圖表的方法。您無需手動建立圖表，而是在文字檔案中編寫程式碼來定義圖表的結構、組件和連接。

然後該程式碼被轉換為圖形圖像，從而更容易在軟體專案中整合和記錄。它對於以程式設計方式建立和更新架構圖和流程圖特別有用。

？圖表即程式碼：建立雲(yún)圖的範例

如前所述，圖表允許您使用主要雲(yún)端技術的圖示來產生藍圖。這些圖表的表示是透過節(jié)點完成的，在我們的範例中，我們將使用所有與雲(yún)端相關的節(jié)點和 AWS 服務。

有關我如何創(chuàng)建它的更多詳細信息，您可以閱讀我關於圖表即代碼的文章，完整的實現(xiàn)可以在此存儲庫中找到：

---

？用例：為機器學習專案建立文件站點

在此用例中，我將為 機器學習專案 建立一個文件網(wǎng)站，涉及 ?醫(yī)院資料。目標是最初使用 MkDocs 建立一個互動式文件站點，然後將其遷移到 Docusaurus。該網(wǎng)站將包括靜態(tài)和動態(tài)元件以滿足特定要求，例如嵌入視覺化圖表和從 SQLite 資料庫動態(tài)更新資料。

---

？文件站點的主要功能

1. 視覺表示：我將嵌入使用圖表（圖表即程式碼）建立的圖表來有效地說明機器學習管道的架構。
2. 動態(tài)資料更新：文件將動態(tài)顯示版本和上次更新日期，從SQLite 資料庫提取此資訊以確保準確性和相關性。
3. 資料範例：文件將包含 Synthea 患者表中的範例，以展示合成資料作為範例。

---

？網(wǎng)站頁面

因此，我們的文件網(wǎng)站將包含以下頁面：

• ？ Home：文件的主頁。
• ？表格：Synthea 資料表及其用途的說明。
• ？架構：託管在 AWS 上的資料處理架構的詳細概述。
• ？詞彙表：整個專案中使用的術語表

---

MkDocs 實施

在本節(jié)中，我們將逐步完成使用 MkDocs 從頭開始設定文件項目的步驟，並解釋其組織的目錄結構。

？ MkDocs 的先決條件

首先，您需要安裝以下 ?Python 庫：

安裝 MkDocs 和材質

  pip install mkdocs mkdocs-material

安裝額外的庫以啟用動態(tài)內容更新

  pip install aiosql pandas sqlite3 jinja2 shutil

---

？ Mkdocs：專案設定

初始化項目

首先建立一個新的 MkDocs 專案。在終端機中執(zhí)行以下命令：

   mkdocs new mkdocs
   cd mkdocs

此指令建立一個具有預設結構的基本 MkDocs 專案。

探索目錄結構

建立 MkDocs 網(wǎng)站後，您需要新增下列檔案和資料夾，因為預設不包含它們。?
請記住，本文末尾提供了儲存庫的連結供您參考，以下將詳細解釋每個元件。

  pip install mkdocs mkdocs-material

---

?Mkdocs：元件概述

---

？ Mkdocs：設定 mkdocs.yml

一旦我們設定了專案結構，我們將從 mkdocs.yml 檔案開始逐步配置它。此文件定義文檔站點的結構和設定。它的結構如下：

mkdocs.yml

  pip install mkdocs mkdocs-material

在此設定檔中，您主要可以在nav部分中看到可從選單存取的頁面。然後，我們指定 Mermaid 擴展，這將在下一節(jié)中解釋。最後，主題部分套用Material主題，啟用該庫中可用的樣式和元件。

---

?? Mkdocs：美人魚擴展

如前所述，Mermaid 是一個 JavaScript 函式庫，用於從文字建立圖表和圖表。下面，我們將看到一些例子。在我們的例子中，我們將使用它在文件的表頁面上產生實體關係圖（ERD）。

在儲存庫中，您將能夠了解如何根據(jù) Synthea 官方文件中的實體關係圖 (ERD) 建立此程式碼。您也可以在以下連結中查看表格頁面的範例：tables.md.

---

?? Mkdocs：使用 Jinja 的動態(tài)內容

為了為我們的文件網(wǎng)站啟用動態(tài)內容生成，我們將使用 Jinja 來處理範本並用實際資料取代佔位符。以下是逐步細分：

1. 設定範本資料夾
   
   建立一個名為 templates 的資料夾來儲存網(wǎng)站的所有 Markdown 檔案。這些檔案應包含佔位符。例如，在index.md中，您可能有像{{database.version_date}}和{{database.version}}這樣的佔位符。

2. 使用佔位符
   
   佔位符是 Markdown 檔案中的動態(tài)變數(shù)。這些變數(shù)將使用Python字典自動更新以注入相關資料。

3. 使用 update.py 產生動態(tài)內容

   • 透過辨識需要動態(tài)資料的部分來準備 Markdown 範本。
   • 使用我的儲存庫中提供的 Python 腳本 (update.py) 來處理範本。該腳本執(zhí)行以下任務：
     • 資料庫連線：連接到 SQLite 資料庫以取得最新值。
     • 範本渲染：使用 Jinja 函式庫以資料庫中的資料取代佔位符。
     • 檔案產生：將更新的 Markdown 檔案輸出到 docs 資料夾，準備在 MkDocs 中渲染。

  pip install mkdocs mkdocs-material

  pip install aiosql pandas sqlite3 jinja2 shutil

透過執(zhí)行這些步驟，您可以自動執(zhí)行文件網(wǎng)站的更新過程，確保內容保持動態(tài)和相關性，而無需手動編輯。

---

資料表動態(tài)更新

在下一個範例中，我們將更新tables.md 檔案中的內容以顯示資料庫中的persons 表的範例。為此，我們將在 Markdown 檔案中建立一個佔位符 {{table.person}}。這個想法是動態(tài)地從 persons 表中獲取數(shù)據(jù)，然後使用 Jinja 庫和 pandas 將查詢結果轉換為 Markdown 表格式。

以下是使用佔位符時tables.md 檔案的外觀範例：

   mkdocs new mkdocs
   cd mkdocs

流程如下：

1. 查詢資料庫：腳本將查詢SQLite資料庫中的persons表格以取得相關記錄。
2. 轉換為 Markdown：使用 pandas，將查詢結果轉換為 Markdown 表格格式
3. 取代佔位符：tables.md 檔案中的 {{table.person}} 佔位符將會被產生的 Markdown 表格取代。

   ? docs/
     ├── ? img/
     ├── `architecture.md`
     ├── `glossary.md`
     ├── `index.md`
     ├── `tables.md`
     ├── ? template/
     │   ├── ? db/
     │   │   ├── ? data/
     │   │   │   ├── hospital.db
     │   │   ├── ? queries/
     │   ├── `architecture.md`
     │   ├── `glossary.md`
     │   ├── `index.md`
     │   ├── `tables.md`
     │   └── `update.py`
   ? infraestructure/
   ? github/
     ├── ? workflows/
     │   ├── main.yml
   ? mkdocs.yml

這樣，文件總是反映最新數(shù)據(jù)，根據(jù)資料庫中的實際內容顯示動態(tài)範例。

---

?? Mkdocs：最終工作流程

1. 建立範本：在 docs/template 目錄中開發(fā)頁面。
2. 執(zhí)行 update.py：填滿動態(tài)內容並在 docs/output 中產生最終檔案。
3. 本機預覽：使用 mkdocsserve 在本機上預覽網(wǎng)站。
4. 建置部署：使用 mkdocs build 在 docs/ 資料夾中產生靜態(tài)網(wǎng)站。
5. 部署：使用 Terraform 將網(wǎng)站部署到 AWS S3 儲存桶。有關詳細說明，請參閱本文的部署部分。

---

？ Docusaurus 實施

在以下部分中，我將提供有關如何使用 Docusaurus 實現(xiàn)文件網(wǎng)站的詳細步驟和見解。這包括設定、自訂和部署選項。

---

？ Docusaurus 的主要特點

• ？ Mermaid 支援：與 MkDocs 類似，Docusaurus 支援 Mermaid 嵌入圖表。
• ?? React 組件：Docusaurus 基於 React 構建，可以將動態(tài)組件整合到文件中。
• ？ 動態(tài)內容：利用 Python 腳本從 SQLite 資料庫動態(tài)取得並更新內容。

---

？ Docusaurus 設定：從頭開始

要開始使用 Docusaurus，我們遵循快速設定流程，該過程與我們用於 MkDocs 的步驟非常相似，但使用不同的工具。

1. 建立一個新的 Docusaurus 專案： 首先，安裝 Node.js 並執(zhí)行以下命令來建立新的 Docusaurus 網(wǎng)站：

  pip install mkdocs mkdocs-material

1. 安裝美人魚包： 若要啟用美人魚圖，請安裝所需的軟體套件：

  pip install aiosql pandas sqlite3 jinja2 shutil

1. 運行開發(fā)伺服器： 安裝後，導航到您的專案目錄並運行開發(fā)伺服器：

   mkdocs new mkdocs
   cd mkdocs

1. 訪問網(wǎng)站： 您的網(wǎng)站將在本地運行：http://localhost:3000。

---

？ Docusaurus 客製化：配置

設定檔 docusaurus.config.js 是我們自訂標題、主題、導覽以及啟用 Mermaid 等功能以進行圖表渲染的地方。
啟用美人魚的範例片段：

  pip install mkdocs mkdocs-material

---

？ Docusaurus 自訂首頁

為了自訂首頁，我們修改 src/components/HomepageFeatures/index.js 檔案。在這裡，您可以調整 FeatureList 物件來更新主頁上顯示的功能。

---

？ Docusaurus 內容組織與結構

就像在 MkDocs 中一樣，Docusaurus 支援 Markdown 文件 作為內容，我們按如下方式組織結構：

1. 範本資料夾：將 Markdown 檔案儲存在 docs/template 目錄中，並建立??一個 Python 腳本（類似於 update.py）來取得動態(tài)資料並將其填入這些範本中。
2. 類別文件 (__category__.json)：要管理側邊欄中文件的順序，請在每個資料夾中建立一個 __category__.json 檔案。例如：

  pip install aiosql pandas sqlite3 jinja2 shutil

__category__.json 範例:

   mkdocs new mkdocs
   cd mkdocs

---

?? Jinja 的動態(tài)數(shù)據(jù)

為了合併動態(tài)內容，例如資料庫表，我們使用名為 update.py 的 ?Python 腳本，您可以在儲存庫中找到該腳本。

此腳本從 SQLite 資料庫取得資料並處理儲存在 templates 資料夾中的 Markdown 檔案。然後，它使用獲取的資料更新這些文件，並將它們複製到 docs 資料夾中，為網(wǎng)站渲染做好準備。

此工作流程確保內容保持最新並準備好部署，遵循與我們使用 MkDocs 實現(xiàn)的類似方法。

---

?? Docusaurus：最終工作流程

1. 建立模板：在 docs/template 目錄中開發(fā) Markdown 檔案。
2. 執(zhí)行Python腳本：使用腳本將資料動態(tài)填入範本中。
3. 本地預覽：執(zhí)行 npx docusaurus start 預覽網(wǎng)站。
4. 建置部署：準備好後，使用 npx docusaurus build 產生靜態(tài)網(wǎng)站。
5. 部署：在您首選的平臺上託管靜態(tài)文件，例如 AWS S3。

---

？部署

在本節(jié)中，我們將介紹使用 AWS S3 進行託管的 MkDocs 和 Docusaurus 的部署流程Docusaurus部署流程。雖然這兩種工具的部署步驟相同，但安裝過程有所不同，MkDocs 基於 Python，

Docusaurus

---

基於 JavaScript。

使用 Terraform 進行基礎架構設置 要將靜態(tài)文件網(wǎng)站部署到 AWS S3，我們使用 Terraform 來預置和配置所需的資源。此設定定義了 S3 儲存桶，啟用靜態(tài)網(wǎng)站託管，並使用儲存桶策略配置公共存取以允許唯讀存取。您可以在儲存庫中找到

main.tf

---

檔案。

？ S3 部署的關鍵元件
S3 儲存桶建立
2. ：用於建立將託管文件的 S3 儲存桶的資源。
靜態(tài)網(wǎng)站託管
3. ：靜態(tài)網(wǎng)站託管配置，設定index.html和error.html為主文件和錯誤文件。
公共存取配置
4. ：管理對 S3 儲存桶的公共訪問，確保將其配置為唯讀存取。
儲存桶策略

：允許公眾存取從 S3 儲存桶檢索文件內容。

您可以存取完整的

Terraform 檔案

以及在儲存庫中部署網(wǎng)站的相應配置：

Terraform 設定檔

：
• mkdocs 文件

docusaurus 文件

自動部署的 GitHub Action 工作流程

：儲存庫中也包含用於自動化部署流程的 CI/CD 管道。
• mkdocs 文件

docusaurus 文件

GitHub 操作配置 確保在設定 >下的GitHub儲存庫機密中配置您的AWS憑證。 秘密 >

行動

。這將允許 GitHub Actions 安全地存取您的 AWS 帳戶，並在您將變更推送到主分支時執(zhí)行將檔案上傳到 S3 等操作。

---

儲存庫

以下是部署文件網(wǎng)站的所有程式碼的連結。如果覺得有用，可以給個star??，追蹤我即可接收新文章通知。這將幫助我在技術社群中成長並創(chuàng)造更多內容。

• MkDocs 部署：MkDocs 的 GitHub 儲存庫

• Docusaurus 部署：Docusaurus 的 GitHub 儲存庫

---

？最終結論：MkDocs 與 Docusaurus

這兩種解決方案都很容易實現(xiàn)，但在以下項目中，我們可以探索一些差異，什麼是最佳解決方案取決於您可能需要實現(xiàn)的上下文、知識和複雜性。

• ？ 語言與客製化： MkDocs 基於 Python，具有簡單的 YAML 配置和模板，非常適合快速設定。另一方面，Docusaurus 基於 React，提供高級自訂和互動組件，使其更適合需要更多視覺控制的用戶。
• ？ 降價與渲染： 兩者都使用 Markdown，但 Docusaurus 允許互動元素，使其更適合動態(tài)內容。
• ?? 複雜性： Docusaurus 更適合複雜的文件應用程序，例如具有登入系統(tǒng)的應用程式。 MkDocs 更簡單，但 Docusaurus 為樣式和功能提供了更大的靈活性。
• ？ 社區(qū)： Docusaurus 擁有強大的社區(qū)，包含 Discord 和 74 個插件，而 MkDocs 則依賴 GitHub 討論來獲得社區(qū)支持。
• ?? 亞馬遜部署： 您可以將靜態(tài)網(wǎng)站部署到S3，降低部署成本，也可以使用CI/CD進行自動部署。

---

？參考

1. Mkdocs：https://www.mkdocs.org/
2. Mkdocs-Material：https://squidfunk.github.io/mkdocs-material/
3. 圖表：https://diagrams.mingrammer.com/
4. Docusaurus：https://docusaurus.io/
5. Jinja：https://jinja.palletsprojects.com/en/stable/
6. Git 書籍 - 什麼是 doc as code：https://www.gitbook.com/blog/what-is-docs-as-code
7. 撰寫文件：https://www.writethedocs.org/guide/docs-as-code/

以上是在 AWS 上部署文件即程式碼：在 MkDocs 和 Docusaurus 中建置動態(tài)文件站點的詳細內容。更多資訊請關注PHP中文網(wǎng)其他相關文章！