文件即程式碼的實際應用：記錄 Python 函式庫。

文件是幫助您的目標受眾了解如何有效使用您的產品的重要資源。高品質的文件不僅傳達了產品解決的核心問題，還使用戶能夠無縫地實現他們想要的結果。

對於開源程式庫和套件來說也是如此。清晰且易於存取的文件對於指導開發人員如何將這些工具成功整合到他們的專案中至關重要。

近年來，文件即程式碼 (DaC) 文件方法已廣受歡迎。此方法透過使用開發人員依賴程式碼的相同工具和流程，將文件視為軟體開發生命週期的基本部分。

這種方法被廣泛接受，因為它促進了一致的、版本控制的、易於維護的文檔，並與產品一起發展。

什麼是文檔即程式碼？

簡單來說，DaC 是一種涉及處理和維護文件的方法，就像處理程式碼一樣。

典型的軟體開發生命週期涉及 7 個階段，其中包括以下階段：

1. 計畫
2. 收集需求與分析
3. 設計
4. 編碼與實作
5. 程式碼測試
6. 程式碼部署
7. 程式碼維護

因此，DaC 是一種確保文件經歷相同階段的新方法。這可以保持文件的版本並隨著軟體變更而保持最新。

不使用 DaC 部署

使用 DaC 部署

雖然本指南可能不會深入探討 DaC 的理論方面，但您可以探索文檔即程式碼初學者指南文章，其中詳細解釋了 DaC 背後的概念。

項目概況

本指南涉及使用 Python 進行 DaC 的實際實作。您將學習如何使用 Mintlify 記錄開源 Python 程式庫。

Mintlify 是一個靜態站點產生器和文件站點，用於面向公眾的文檔。它易於維護和使用，可滿足各種文件需求，例如開發人員文件、API 文件等。它也與 DaC 方法論配合良好。

本教學是有關如何建置和部署 Python 程式庫的現有教學的續集。使用 DaC 方法，您將學習如何記錄 Python 庫開發的參考教學。

建議您先完成之前的教程，然後再繼續。但是，如果您有可用於本教程的現有項目，則可以繼續。

項目要求

需要具備 Git 和 GitHub 的基本知識，如何建立 Github 儲存庫以及如何將程式碼推送到 GitHub。本教學還需要以下工具：

• Mintlify 帳戶： 您需要一個活躍的 Mintlify 帳戶來建立文件（指南中將提供步驟）。
• Node.js：您需要 Node.js 版本 18 及更高版本才能安裝 Mintlify 並在本地編輯文件。

設定 Mintlify 文檔

依照以下步驟使用 Mintlify 設定文件：

1。在 Mintlify 上建立帳戶

2。設定您的 Mintlify 帳號：
驗證連結將發送到您的郵箱。此連結會將您重新導向至以下頁面：

3。使用 Github 登入：
第一步需要您使用 Github 帳戶登入。

4。為您的文件建立 GitHub 儲存庫 (repo)：
下一步需要您在 Github 帳戶上安裝並授權 Mintlify 應用程式。這允許 Mintlify 自動為您的文件建立一個儲存庫

5。存取您的文件儲存庫：
上一步為您的文件建立一個新的文檔儲存庫。檢查您的 GitHub 儲存庫中是否有新的文件儲存庫

將文件新增至您的專案中

下一步是將文件儲存庫複製到您的本機環境並將其新增至現有專案中，例如開發人員工具、開源套件等。如果您已經完成了上一個教學課程，您的專案將是 ExchangeLibrary。

請按照以下步驟將文件新增至您的專案：

1。開啟終端機並使用以下命令複製文件儲存庫：

git clone https://github.com/<your github username>/docs 

2。將克隆的 docs 資料夾複製到您的專案。

3。在程式碼編輯器中開啟項目。

您的專案文件結構現在應如下所示：

本地預覽文檔

Mintlify 允許您在發布文件之前在本機預覽文件。請依照以下步驟進行設定：
1.在終端機中開啟您的專案
2.執行以下命令以全域安裝 Mintlify：

git clone https://github.com/<your github username>/docs 

3。切換到專案中的 docs 資料夾：

npm i -g mintlify

4。使用以下命令啟動 mintlify 伺服器：

cd docs

您應該在終端機中看到如下所示的訊息：

開啟URL即可在本機預覽文件。您的文件內容將是 Mintlify 入門文件範本。當您開始編輯文件時，這將會改變。

撰寫文件

Mintlify 文件由 mint.json 檔案支援。此文件包含文件的配色方案、分頁和導覽設定。您可以在專案的 docs 資料夾中找到它。

此外，Mintlify 中的文件檔案是用 .mdx 編寫的。它幾乎與 markdown(.md) 類似，只是它允許特殊的標籤和符號。

在本節中，您將學習如何在 mint.json 文件中編輯文件設置，以及如何向文件添加文字和特殊組件。

編輯文檔設定

mint.json 檔案是 JSON 對象，由文件的配色方案、分頁、導覽設定等組成。以下是可用設定及其含義的清單：

1。配色與外觀：
此部分用於美化和增強您的文件外觀。它用於更改文件的徽標（淺色和深色模式）、圖標、標題和配色方案。它從 $schema 鍵開始到顏色鍵，如下所示：

mintlify dev

2。導航連結和 CTA 按鈕：
此部分用於在文件頁面頂部設定導航連結和按鈕。以下是導航連結和按鈕的範例：

下面的程式碼為您的 Mintlify 文件設定導覽連結和 CTA 按鈕：

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },

3。選項卡和錨點：
選項卡和錨點可用於分別在文件中設定水平和垂直部分。以下是選項卡範例：

以下是錨點的範例：

這些組件的設定由選項卡和錨點鍵處理。

4。導航設定：
本部分可協助您將文件中的頁面分組。它是一個由組鍵和頁面數組組成的數組，其中按順序添加該組的頁面。以下是如何添加的範例：

git clone https://github.com/<your github username>/docs 

上面的設定將轉換為下圖：

頁面（簡介等）是專案文件夾中的 .mdx 檔案。

5。嵌套導航：
嵌套導航通常用於在文件中建立小節。以下是巢狀導航的範例：

以下是在 Mintlify 上設定巢狀導覽的範例程式碼：

npm i -g mintlify

上面的程式碼將一個部分/群組嵌套在另一個部分中。圖示鍵在網頁上呈現時用圖示美化章節標題。

6。頁腳設定：
footerSocials 鍵用於新增與文件相關的社群媒體帳號。下面是一個例子：

如何添加內容

Mintlify 文件指導您如何為文件添加內容。我建議您查看文件以了解如何向文件添加不同的內容。

查看此範例文檔，以獲取有關如何建立自己的文檔的靈感。

文件寫作技巧

以下一些提示可協助您撰寫清晰且使用者友善的文件：

1. 盡量直接： 避免沒有任何價值的無關資訊。您的文件適用於想要在下一個專案中使用您的套件或工具的開發人員，因此僅向他們展示實現此目標所需的內容。

2。新增工具的描述或概述：
在詳細介紹如何使用工具之前，請先簡單描述一下您的工具是什麼以及它解決的問題。這應該在第一頁。

3。加入足夠的程式碼範例：
這將幫助他們了解如何使用您的工具，而不會出現不必要的錯誤。有關安裝、身份驗證、回應範例、方法參數等的程式碼範例非常重要。

4。錯誤和異常：
這將有助於用戶調試。新增一個頁面來描述使用者在使用您的工具時可能遇到的錯誤類型。也顯示了這方面的程式碼範例。

將專案推送到Github

依照以下步驟將專案推送到Github：

1。在專案中開啟 git bash 終端，然後使用以下命令切換到 docs 資料夾：

git clone https://github.com/<your github username>/docs 

2。使用以下命令從此資料夾中刪除 git：

npm i -g mintlify

此指令會從 docs 資料夾中刪除 .git，以避免您要將整個專案推送到 Github 時出現問題。

3。將專案推送到 GitHub。

部署文件

按照以下步驟在 Mintlify 上部署您的文件：
1.登入您的 Mintlify 儀表板
2.點選「設定」標籤

3.將您的 Mintlify Github 儲存庫變更為您專案的儲存庫

4.啟動 monorepo 開關。這表示 docs 資料夾存在於單一儲存庫中的另一個項目中。

5。在出現的新欄位中輸入 **docs 作為 mint.json 檔案的路徑。 **

6。點選“儲存”按鈕儲存變更。

您的文件可以透過儀表板概述標籤中顯示的連結存取

更新項目

您最有可能對專案進行更改，並且可能需要重新部署它。

在專案中進行任何更新後，請確保將變更推送到 Github。 Mintlify 會自動取得新的變更並立即更新您的文件。

結論

在本教學課程中，您學習如何使用文件即程式碼方法為 Python 函式庫建置文件。

文件即程式碼促進專案上的協作和持續整合。當談到開源時，文件即程式碼允許人們在專案上無縫協作，同時維護最新的適當文件。

有不同的 REST API，沒有 SDK 或程式庫。選擇您感興趣的一個並創建類似的東西。

繼續建造？ ‍？ ！

常見問題解答

如何測試我的文件？

此功能通常用於具有多個貢獻者的大型專案。當向專案發出拉取請求時，文件測試會自動執行。如果測試成功，則合併變更。閱讀本指南，了解 Swimm 如何提供自動文件測試以了解更多資訊。

我可以用其他程式語言複製這個專案嗎？
是的，你可以。請按照本指南中的步驟操作，以您的首選語言獲得類似的結果。

除了 Mintlify 之外還有其他文件網站嗎？
是的，您也可以使用其他文件網站。其中包括：Gitbook、Readme、Docusaurus 等

以上是文件即程式碼的實際應用：記錄 Python 函式庫。的詳細內容。更多資訊請關注PHP中文網其他相關文章！