在 AWS 上部署文件即程式碼：在 MkDocs 和 Docusaurus 中建置動態文件站點
- Mary-Kate Olsen原創
- 2024-11-28 05:28:11182瀏覽
在本文中，我將指導您一步一步建立一個適用於任何專案的動態文件站點，您可以在其中將文件連接到資料庫以提取和顯示數據，確保資訊始終是最新的。我們也將探索如何使用 AWS.
自動化整個流程，從內容產生到雲端部署此解決方案包括對圖表和圖表的支援、使用 GitHub Actions 中簡單工作流程的持續整合 (CI/CD) 以及使用 Terraform 的自動部署。讓我們開始吧！
什麼是文檔即程式碼？
文件及其更新是許多開發軟體的公司的重要流程，通常使用不同的工具進行，其中許多是付費解決方案。
因此，最近出現了“doc as code”的概念。這意味著使用軟體開發中使用的相同工具和工作流程來管理、版本和部署文件。
這種方法不僅可以更好地追蹤文檔，還可以促進其維護，並確保與軟體開發中使用的相同最佳實踐保持一致，不僅在程式碼中，而且在文件中。
將文件作為程式碼的工具
對於這些網站的開發，有必要了解一些允許我們實施這種方法的實踐和工具。以下是本教程中要涵蓋的最重要方面的詳細清單。
- ？ Markdown：由於其簡單性以及與版本控制平台和靜態站點生成器的集成，是編寫文檔最常用的標記語言。
- ?️ Git：Git 允許像程式碼一樣對文件進行版本控制。感謝 Git，記錄了文件中的每一個更改，使團隊能夠追蹤編輯、恢復更改並更有效地協作。
- ？ Gitflow：此方法提供了一個結構化的工作流程來管理文件的版本和修訂，確保變更在投入生產之前得到批准和測試。 Gitflow 也促進團隊之間的協作，從而實現安全且有組織的變更管理。
- ☁️ 雲端服務：使用 AWS S3、Netlify 或 GitHub Pages 等服務，您可以以較低的成本部署文件。這些服務允許建立快速、安全且易於存取的靜態網站。
- ？ 靜態網站產生器：Docusaurus、Jekyll 或 Hugo 等工具將 Markdown 文件轉換為可導航的網站，讓您無需伺服器即可建立豐富且有組織的文件。
- ？ 持續整合 (CI/CD)：CI/CD 管道（例如 GitHub Actions、GitLab CI 或 Jenkins）可讓您在合併新版本或核准修改時自動部署文件。這可確保文件始終是最新的。
文檔即程式碼的優點
- ✅ 一致性和品質：透過使用版本控制和變更審核，文件保持一致且高品質。
- ⚙️ 自動化：CI/CD 工具可實現文件部署的自動化，減少更新時間並最大限度地減少錯誤。
- ？高效協作：借助 Git 等工具，團隊可以協作創建和維護文檔，而不會發生衝突。
- ？簡化維護：維護文件已整合到開發工作流程中，隨著程式碼的發展，更新變得更加容易。
？ MK文檔
MkDocs 是一個用 ?Python 編寫的靜態網站產生器，專為文件專案而設計。其目標是簡化使用 Markdown 文件建立文檔，這些文件易於編寫和閱讀。
透過最少的配置，MkDocs 將 Markdown 文件轉換為可導航且結構良好的文件網站，使其成為想要保持文件最新的開發人員和團隊的理想選擇。
✏️ MkDocs 材料
MkDocs Material 是 MkDocs 的高級主題，遵循 Google 的 Material Design 指南。
？主要特點包括：
- ？ 響應式設計：自動適應任何螢幕尺寸。
- ？ 自訂：輕鬆修改顏色、字體、圖示和標誌以符合您項目的視覺識別。
- ？ 搜尋介面：進階搜尋將結果分組並突出顯示搜尋的術語，幫助使用者找到所需的資訊。
- ⚡ 延遲加載：對搜尋結果實現延遲加載，提高效能並減少加載時間。
- ？ 整合：相容於Google Analytics、Disqus和GitHub，方便流量分析、使用者回饋以及直接連接到專案儲存庫。
✏️美人魚
Mermaid 是一個 JavaScript 函式庫，用於從文字建立圖表。透過與 MkDocs Material 集成，Mermaid 可讓您在文件中產生視覺化效果，例如流程圖、實體關係圖和文件中的其他圖表，而無需外部工具。
？動態頁：Jinja
Jinja 是一個函式庫，允許將 Python 字典中的變數和資料嵌入到 HTML 中，使網頁動態化。該程式庫通常用於產生動態 HTML 和發送個人化電子郵件。
？多庫龍概述
Docusaurus 是 Meta 於 2007 年開發的開源項目，它以快速且有效率的方式簡化了文件網站的建立、部署和維護。它允許使用 Markdown 和 MDX 來編寫內容，而其基於 React 的核心可以完全自訂樣式，以滿足專案的特定需求。
此外，Docusaurus 透過 @docusaurus/theme-mermaid 插件支援 Mermaid，從而可以直接在文件中包含圖表和圖表。
？圖表即程式碼
圖表即程式碼是一種允許您透過程式碼而不是使用傳統圖形工具來建立圖表的方法。您無需手動建立圖表，而是在文字檔案中編寫程式碼來定義圖表的結構、組件和連接。
然後該程式碼被轉換為圖形圖像，從而更容易在軟體專案中整合和記錄。它對於以程式設計方式建立和更新架構圖和流程圖特別有用。
？圖表即程式碼：建立雲圖的範例
如前所述，圖表允許您使用主要雲端技術的圖示來產生藍圖。這些圖表的表示是透過節點完成的，在我們的範例中，我們將使用所有與雲端相關的節點和 AWS 服務。
有關我如何創建它的更多詳細信息，您可以閱讀我關於圖表即代碼的文章，完整的實現可以在此存儲庫中找到：
羅米門德斯
/
圖表即程式碼
有關如何使用「文件為圖表」方法建立文件項目的教學課程
？圖表即代碼：為視覺內容建立動態和互動式文件
圖表即程式碼是一種允許您透過程式碼而不是傳統圖形工具建立圖表的方法。您可以在文字檔案中編寫程式碼來定義圖表的結構、元件和連接，而不是手動建立圖表。
然後，該程式碼被轉換為圖形圖像，從而更容易在軟體專案中整合和記錄，這對於以程式設計方式建立和更新架構和流程圖特別有用。
什麼是圖表？
Diagrams 是一個 ?Python 庫，它實現了圖表即程式碼方法，使您能夠透過程式碼建立架構基礎設施圖和其他類型的圖表。借助圖表，您只需幾行程式碼即可輕鬆定義雲端基礎架構元件（例如 AWS、Azure 和 GCP）、網路元素、軟體服務等。
？圖即程式碼的好處
- ？ …
？用例：為機器學習專案建立文件站點
在此用例中，我將為 機器學習專案 建立一個文件網站，涉及 ?醫院資料。目標是最初使用 MkDocs 建立一個互動式文件站點，然後將其遷移到 Docusaurus。該網站將包括靜態和動態元件以滿足特定要求，例如嵌入視覺化圖表和從 SQLite 資料庫動態更新資料。
？文件站點的主要功能
- 視覺表示：我將嵌入使用圖表（圖表即程式碼）建立的圖表來有效地說明機器學習管道的架構。
- 動態資料更新：文件將動態顯示版本和上次更新日期，從SQLite 資料庫提取此資訊以確保準確性和相關性。
- 資料範例：文件將包含 Synthea 患者表中的範例，以展示合成資料作為範例。
？網站頁面
因此，我們的文件網站將包含以下頁面：
- ？ Home：文件的主頁。
- ？表格：Synthea 資料表及其用途的說明。
- ？架構：託管在 AWS 上的資料處理架構的詳細概述。
- ？詞彙表：整個專案中使用的術語表
MkDocs 實施
在本節中，我們將逐步完成使用 MkDocs 從頭開始設定文件項目的步驟，並解釋其組織的目錄結構。
？ MkDocs 的先決條件
首先，您需要安裝以下 ?Python 庫：
安裝 MkDocs 和材質
pip install mkdocs mkdocs-material
安裝額外的庫以啟用動態內容更新
pip install aiosql pandas sqlite3 jinja2 shutil
？ Mkdocs：專案設定
初始化項目
首先建立一個新的 MkDocs 專案。在終端機中執行以下命令：
mkdocs new mkdocs cd mkdocs
此指令建立一個具有預設結構的基本 MkDocs 專案。
探索目錄結構
建立 MkDocs 網站後，您需要新增下列檔案和資料夾，因為預設不包含它們。
請記住，本文末尾提供了儲存庫的連結供您參考，以下將詳細解釋每個元件。
pip install mkdocs mkdocs-material
?Mkdocs：元件概述
| Component | Directory | Description |
|---|---|---|
| Database (db) | db | Contains the SQLite database (hospital.db) and queries (metadata.sql, person.sql) to manage dynamic data. Learn more about managing SQL queries in Python in my previous article: Python Projects with SQL. |
| ?️ Templates & Pages | template | Markdown templates: index.md, tables.md, architecture.md, glossary.md. Supports Mermaid diagrams, embedded images, and database-driven content. |
| ?️ Static Content (docs) | docs | Final site generated by update.py, including images (img/) and dynamic content populated from template. |
| ? Infrastructure (infraestructure) | infraestructure | Terraform scripts (main.tf, variables.tf) to deploy an S3 bucket for documentation hosting. |
？ Mkdocs：設定 mkdocs.yml
一旦我們設定了專案結構，我們將從 mkdocs.yml 檔案開始逐步配置它。此文件定義文檔站點的結構和設定。它的結構如下：
mkdocs.yml
pip install mkdocs mkdocs-material
在此設定檔中，您主要可以在nav部分中看到可從選單存取的頁面。然後，我們指定 Mermaid 擴展，這將在下一節中解釋。最後，主題部分套用Material主題，啟用該庫中可用的樣式和元件。
✏️ Mkdocs：美人魚擴展
如前所述，Mermaid 是一個 JavaScript 函式庫，用於從文字建立圖表和圖表。下面，我們將看到一些例子。在我們的例子中，我們將使用它在文件的表頁面上產生實體關係圖（ERD）。
在儲存庫中，您將能夠了解如何根據 Synthea 官方文件中的實體關係圖 (ERD) 建立此程式碼。您也可以在以下連結中查看表格頁面的範例：tables.md.
⚙️ Mkdocs：使用 Jinja 的動態內容
為了為我們的文件網站啟用動態內容生成，我們將使用 Jinja 來處理範本並用實際資料取代佔位符。以下是逐步細分：
設定範本資料夾
建立一個名為 templates 的資料夾來儲存網站的所有 Markdown 檔案。這些檔案應包含佔位符。例如，在index.md中，您可能有像{{database.version_date}}和{{database.version}}這樣的佔位符。使用佔位符
佔位符是 Markdown 檔案中的動態變數。這些變數將使用Python字典自動更新以注入相關資料。-
使用 update.py 產生動態內容
- 透過辨識需要動態資料的部分來準備 Markdown 範本。
- 使用我的儲存庫中提供的 Python 腳本 (update.py) 來處理範本。該腳本執行以下任務：
- 資料庫連線：連接到 SQLite 資料庫以取得最新值。
- 範本渲染：使用 Jinja 函式庫以資料庫中的資料取代佔位符。
- 檔案產生：將更新的 Markdown 檔案輸出到 docs 資料夾，準備在 MkDocs 中渲染。
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
透過執行這些步驟，您可以自動執行文件網站的更新過程，確保內容保持動態和相關性，而無需手動編輯。
資料表動態更新
在下一個範例中，我們將更新tables.md 檔案中的內容以顯示資料庫中的persons 表的範例。為此，我們將在 Markdown 檔案中建立一個佔位符 {{table.person}}。這個想法是動態地從 persons 表中獲取數據，然後使用 Jinja 庫和 pandas 將查詢結果轉換為 Markdown 表格式。
以下是使用佔位符時tables.md 檔案的外觀範例：
mkdocs new mkdocs cd mkdocs
流程如下：
- 查詢資料庫：腳本將查詢SQLite資料庫中的persons表格以取得相關記錄。
- 轉換為 Markdown：使用 pandas，將查詢結果轉換為 Markdown 表格格式
- 取代佔位符：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
這樣，文件總是反映最新數據，根據資料庫中的實際內容顯示動態範例。
⚙️ Mkdocs：最終工作流程
- 建立範本：在 docs/template 目錄中開發頁面。
- 執行 update.py：填滿動態內容並在 docs/output 中產生最終檔案。
- 本機預覽：使用 mkdocsserve 在本機上預覽網站。
- 建置部署：使用 mkdocs build 在 docs/ 資料夾中產生靜態網站。
- 部署：使用 Terraform 將網站部署到 AWS S3 儲存桶。有關詳細說明，請參閱本文的部署部分。
？ Docusaurus 實施
在以下部分中，我將提供有關如何使用 Docusaurus 實現文件網站的詳細步驟和見解。這包括設定、自訂和部署選項。
？ Docusaurus 的主要特點
- ？ Mermaid 支援：與 MkDocs 類似，Docusaurus 支援 Mermaid 嵌入圖表。
- ⚛️ React 組件：Docusaurus 基於 React 構建，可以將動態組件整合到文件中。
- ？ 動態內容：利用 Python 腳本從 SQLite 資料庫動態取得並更新內容。
？ Docusaurus 設定：從頭開始
要開始使用 Docusaurus，我們遵循快速設定流程，該過程與我們用於 MkDocs 的步驟非常相似，但使用不同的工具。
- 建立一個新的 Docusaurus 專案： 首先，安裝 Node.js 並執行以下命令來建立新的 Docusaurus 網站：
pip install mkdocs mkdocs-material
- 安裝美人魚包： 若要啟用美人魚圖，請安裝所需的軟體套件：
pip install aiosql pandas sqlite3 jinja2 shutil
- 運行開發伺服器： 安裝後，導航到您的專案目錄並運行開發伺服器：
mkdocs new mkdocs cd mkdocs
- 訪問網站： 您的網站將在本地運行：http://localhost:3000。
？ Docusaurus 客製化：配置
設定檔 docusaurus.config.js 是我們自訂標題、主題、導覽以及啟用 Mermaid 等功能以進行圖表渲染的地方。
啟用美人魚的範例片段：
pip install mkdocs mkdocs-material
？ Docusaurus 自訂首頁
為了自訂首頁，我們修改 src/components/HomepageFeatures/index.js 檔案。在這裡，您可以調整 FeatureList 物件來更新主頁上顯示的功能。
？ Docusaurus 內容組織與結構
就像在 MkDocs 中一樣，Docusaurus 支援 Markdown 文件 作為內容，我們按如下方式組織結構：
- 範本資料夾：將 Markdown 檔案儲存在 docs/template 目錄中，並建立一個 Python 腳本（類似於 update.py）來取得動態資料並將其填入這些範本中。
- 類別文件 (__category__.json)：要管理側邊欄中文件的順序，請在每個資料夾中建立一個 __category__.json 檔案。例如：
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json 範例:
mkdocs new mkdocs cd mkdocs
⚙️ Jinja 的動態數據
為了合併動態內容，例如資料庫表，我們使用名為 update.py 的 ?Python 腳本，您可以在儲存庫中找到該腳本。
此腳本從 SQLite 資料庫取得資料並處理儲存在 templates 資料夾中的 Markdown 檔案。然後，它使用獲取的資料更新這些文件，並將它們複製到 docs 資料夾中，為網站渲染做好準備。
此工作流程確保內容保持最新並準備好部署，遵循與我們使用 MkDocs 實現的類似方法。
⚙️ Docusaurus：最終工作流程
- 建立模板：在 docs/template 目錄中開發 Markdown 檔案。
- 執行Python腳本：使用腳本將資料動態填入範本中。
- 本地預覽：執行 npx docusaurus start 預覽網站。
- 建置部署：準備好後，使用 npx docusaurus build 產生靜態網站。
- 部署：在您首選的平台上託管靜態文件，例如 AWS S3。
？部署
在本節中，我們將介紹使用 AWS S3 進行託管的 MkDocs 和 Docusaurus 的部署流程Docusaurus部署流程。雖然這兩種工具的部署步驟相同，但安裝過程有所不同，MkDocs 基於 Python，
Docusaurus基於 JavaScript。
使用 Terraform 進行基礎架構設置 要將靜態文件網站部署到 AWS S3，我們使用 Terraform 來預置和配置所需的資源。此設定定義了 S3 儲存桶，啟用靜態網站託管，並使用儲存桶策略配置公共存取以允許唯讀存取。您可以在儲存庫中找到
main.tf檔案。
-
？ S3 部署的關鍵元件
- S3 儲存桶建立
- ：用於建立將託管文件的 S3 儲存桶的資源。 靜態網站託管
- ：靜態網站託管配置，設定index.html和error.html為主文件和錯誤文件。 公共存取配置
- ：管理對 S3 儲存桶的公共訪問，確保將其配置為唯讀存取。 儲存桶策略
您可以存取完整的
Terraform 檔案以及在儲存庫中部署網站的相應配置：
Terraform 設定檔- ：
- mkdocs 文件
自動部署的 GitHub Action 工作流程
- ：儲存庫中也包含用於自動化部署流程的 CI/CD 管道。
- mkdocs 文件
。這將允許 GitHub Actions 安全地存取您的 AWS 帳戶，並在您將變更推送到主分支時執行將檔案上傳到 S3 等操作。行動
GitHub 操作配置 確保在設定 >下的GitHub儲存庫機密中配置您的AWS憑證。 秘密 >
儲存庫
以下是部署文件網站的所有程式碼的連結。如果覺得有用，可以給個star⭐️，追蹤我即可接收新文章通知。這將幫助我在技術社群中成長並創造更多內容。- MkDocs 部署：MkDocs 的 GitHub 儲存庫
羅米門德斯
/
文檔即程式碼 mkdocs
有關如何使用「文檔即程式碼」方法建立文件項目的教學課程
⚙️ 文件即程式碼教學
？ MkDocs 和 MkDocs-材料
MkDocs 是實現文件入口網站的絕佳解決方案，可以使用程式碼輕鬆更新，幫助您的軟體開發專案文件保持最新和版本控制。
在此儲存庫中，我建立了一個簡單的網站來記錄資料模型和機器學習專案。
文件將包括圖表、表格和架構範例，提供全面且易於理解的指南，指導如何結合其他兩個 ?Python 函式庫來實現此框架。
什麼是文檔即程式碼？
文件及其更新是許多開發軟體的公司的一個重要流程，該流程是使用不同的工具執行的，其中許多是付費解決方案。
因此，最近出現了“doc as code”的概念。這意味著使用軟體開發中使用的相同工具和工作流程來管理、版本和......
- Docusaurus 部署：Docusaurus 的 GitHub 儲存庫
羅米門德斯
/
文檔即程式碼 docusaurus
有關如何使用「文檔即程式碼」方法建立文件項目的教學課程
⚙️ 文件即程式碼教學
？多庫龍
Docusaurus 是實現文件入口網站的絕佳解決方案，可以使用程式碼輕鬆更新，幫助您的軟體開發專案文件保持最新和版本控制。
在此儲存庫中，我建立了一個簡單的網站來記錄資料模型和機器學習專案。
文件將包括圖表、表格和架構範例，提供全面且易於理解的指南，指導如何結合其他兩個 ?Python 函式庫來實現此框架。
什麼是文檔即程式碼？
文件及其更新是許多開發軟體的公司的一個重要流程，該流程是使用不同的工具執行的，其中許多是付費解決方案。
因此，最近出現了“doc as code”的概念。這意味著使用軟體開發中使用的相同工具和工作流程來管理、版本和部署文件......
？最終結論：MkDocs 與 Docusaurus
這兩種解決方案都很容易實現，但在以下項目中，我們可以探索一些差異，什麼是最佳解決方案取決於您可能需要實現的上下文、知識和複雜性。
- ？ 語言與客製化： MkDocs 基於 Python，具有簡單的 YAML 配置和模板，非常適合快速設定。另一方面，Docusaurus 基於 React，提供高級自訂和互動組件，使其更適合需要更多視覺控制的用戶。
- ？ 降價與渲染： 兩者都使用 Markdown，但 Docusaurus 允許互動元素，使其更適合動態內容。
- ⚙️ 複雜性： Docusaurus 更適合複雜的文件應用程序，例如具有登入系統的應用程式。 MkDocs 更簡單，但 Docusaurus 為樣式和功能提供了更大的靈活性。
- ？ 社區： Docusaurus 擁有強大的社區，包含 Discord 和 74 個插件，而 MkDocs 則依賴 GitHub 討論來獲得社區支持。
- ☁️ 亞馬遜部署： 您可以將靜態網站部署到S3，降低部署成本，也可以使用CI/CD進行自動部署。
？參考
- Mkdocs：https://www.mkdocs.org/
- Mkdocs-Material：https://squidfunk.github.io/mkdocs-material/
- 圖表：https://diagrams.mingrammer.com/
- Docusaurus：https://docusaurus.io/
- Jinja：https://jinja.palletsprojects.com/en/stable/
- Git 書籍 - 什麼是 doc as code：https://www.gitbook.com/blog/what-is-docs-as-code
- 撰寫文件：https://www.writethedocs.org/guide/docs-as-code/
以上是在 AWS 上部署文件即程式碼：在 MkDocs 和 Docusaurus 中建置動態文件站點的詳細內容。更多資訊請關注PHP中文網其他相關文章！