Python套件檔案撰寫與託管

Python 生態系統蓬勃發展，良好的套件檔案是確保專案成功的關鍵。本文將引導您使用業界最佳實務，包含撰寫清晰的 README、使用 Numpydoc 風格的 docstring、利用 Sphinx 建立檔案網站，並最終將檔案託管至 Read the Docs，提升專案的易用性和可維護性。從程式碼註解到線上檔案，我們將逐步說明如何開發專業的檔案，讓您的 Python 套件更容易被社群理解和使用。

開發專業的Python套件檔案

撰寫高品質的檔案對於Python套件的成功至關重要。本章節將探討如何建立完整的套件檔案，包括README、變更日誌、貢獻和程式碼註解。

編寫README檔案

README檔案是使用者瞭解套件的第一手資料。我們使用Markdown語法編寫README，以確保其在各種平台上的可讀性。

README範例

# pycounts
計算文字檔中的字詞數量！

## 安裝
```bash
$ pip install pycounts

使用方法

pycounts可用於計算文字檔中的字詞數量並繪製結果，如下所示：

from pycounts.pycounts import count_words
from pycounts.plotting import plot_words
import matplotlib.pyplot as plt

file_path = "test.txt"  # 您的檔案路徑
counts = count_words(file_path)
fig = plot_words(counts, n=10)
plt.show()

貢獻

有興趣貢獻？請檢視貢獻。請注意，此專案發布時附帶行為準則。透過貢獻此專案，您同意遵守其條款。

授權

pycounts由Tomas Beuzen建立。根據MIT授權條款授權。

致謝

pycounts使用cookiecutter和py-pkgs-cookiecutter範本建立。


#### 內容解密：
1. 使用Markdown語法編寫README，使其在多個平台上可讀。
2. 包含安裝、使用方法、貢獻、授權和致謝等必要資訊。
3. 使用程式碼區塊展示安裝和使用方法。
4. 提供貢獻和行為準則的連結。

### 編寫程式碼註解

程式碼註解（docstring）是Python中用於記錄函式、類別和模組的重要工具。它們在使用者呼叫`help()`函式時顯示，對於理解套件功能至關重要。

#### 編寫高品質註解的原則

1. 簡潔明瞭的摘要，不使用變數名稱或函式名稱。
2. 詳細的描述。
3. 引數型別和描述。
4. 傳回值型別和描述。
5. 使用範例。

#### numpydoc風格註解範例

```python
def count_words(input_file):
    """計算文字檔中的字詞數量。
    
    在計數之前，將文字轉換為小寫並移除標點符號。
    
    Parameters
    
---
-
---
---
    input_file : str
        文字檔的路徑。
    
    Returns
    
---
-
---
    collections.Counter
        一個類別似字典的物件，鍵為字詞，值為計數。
    
    Examples
    
---
-
---
-
    >>> count_words("text.txt")
    """
    text = load_text(input_file)
    text = clean_text(text)
    words = text.split()
    return Counter(words)

內容解密：

使用numpydoc風格編寫註解，使其易於閱讀和被sphinx支援。
包含簡要摘要、詳細描述、引數、傳回值和使用範例等資訊。
正確使用縮排和格式，以提高可讀性。

建立檔案網站

建立檔案網站可讓使用者更方便地存取套件資訊。我們可以使用Sphinx等工具將Markdown或reStructuredText檔案轉換為HTML檔案。

線上託管檔案

將檔案託管線上上的免費服務（如Read the Docs或GitHub Pages）上，可讓任何有網路連線的人輕鬆存取。

3.8 套件檔案編寫

撰寫完善的檔案對於套件的使用者來說至關重要。良好的檔案不僅可以幫助使用者瞭解套件的功能和使用方法，還能減少使用者的困惑和錯誤。

3.8.1 檔案內容

在前面的章節中，我們已經為 pycounts 套件撰寫了基本的說明檔案，包括 README.md 和函式的 docstring。現在，我們將進一步完善這些檔案。

使用 numpydoc 風格的 docstring

我們採用 numpydoc 風格來撰寫 docstring。這種風格的檔案結構清晰，易於閱讀和理解。下面是一些範例：

def plot_words(word_counts, n=10):
    """繪製詞頻的長條圖。

    Parameters
    
---
-
---
---
    word_counts : collections.Counter
        詞頻的 Counter 物件。
    n : int, optional
        繪製前 n 個詞頻，預設為 10。

    Returns
    
---
-
---
    matplotlib.container.BarContainer
        詞頻的長條圖。

    Examples
    
---
-
---
-
    >>> from pycounts.pycounts import count_words
    >>> from pycounts.plotting import plot_words
    >>> counts = count_words("text.txt")
    >>> plot_words(counts)
    """
    top_n_words = word_counts.most_common(n)
    word, count = zip(*top_n_words)
    fig = plt.bar(range(n), count)
    plt.xticks(range(n), labels=word, rotation=45)
    plt.xlabel("Word")
    plt.ylabel("Count")
    return fig

檔案內容解密：

plot_words 函式用於繪製詞頻的長條圖。
word_counts 引數是詞頻的 Counter 物件。
n 引數用於指定繪製前 n 個詞頻，預設為 10。
函式傳回一個 matplotlib.container.BarContainer 物件，表示詞頻的長條圖。

3.8.2 建立 API 參考檔案

為了方便使用者查閱套件的功能和用法，我們需要建立一個 API 參考檔案。這個檔案可以透過 sphinx 自動生成。

為什麼使用 sphinx？

sphinx 是一個強大的檔案生成工具，可以自動解析原始碼，提取函式和 docstring，並生成 API 參考檔案。使用 sphinx 可以節省時間和精力，避免手動複製和貼上程式碼。

3.8.3 建立使用範例

建立使用範例是幫助使用者瞭解套件功能和用法的重要一步。我們可以使用 Jupyter Notebooks 來建立互動式的使用範例。

為什麼使用 Jupyter Notebooks？

Jupyter Notebooks 是一種互動式的檔案格式，可以包含程式碼、方程式、文字和視覺化結果。使用 Jupyter Notebooks 可以讓使用者直接執行和互動範例程式碼，從而更好地瞭解套件的功能和用法。

建立 Jupyter Notebook 範例

首先，我們需要安裝 jupyter：

$ poetry add --dev jupyter

然後，開啟 Jupyter Notebook 應用程式：

$ jupyter notebook

在介面中，導航到 docs/example.ipynb 並開啟它。我們可以更新這個 notebook，加入 Markdown 和程式碼單元格，示範套件的基本用法。

3.8.4 建立檔案網站

現在，我們已經撰寫了套件的各個部分的檔案，包括 docstring、使用範例等。接下來，我們將使用 sphinx 將這些檔案編譯成一個易於導航的檔案網站。

使用 sphinx 自動執行 notebook

sphinx 可以自動執行 Jupyter Notebooks，並將其內容（包括程式碼輸出）納入編譯好的檔案中。這樣，使用者就可以在不需要啟動 Jupyter 應用程式的情況下，閱讀和使用套件的檔案。

開發專業的Python套件檔案

在前一節中，我們已經成功建立了一個名為pycounts的Python套件。現在，我們將進一步探討如何為這個套件建立專業的檔案。良好的檔案不僅能夠幫助使用者快速上手，也能提高套件的可維護性和可擴充套件性。

為什麼需要檔案生成工具？

隨著套件功能的增加，檔案編寫的工作量也會隨之增加。手動維護檔案不僅耗時，而且容易出現檔案與程式碼不一致的問題。這時，檔案生成工具sphinx就派上用場了。sphinx能夠自動從程式碼中的docstring生成API參考，並且支援將Jupyter Notebook轉換為檔案的一部分。

使用`sphinx`生成檔案

sphinx是一個強大的工具，能夠將純文字源檔案編譯成使用者友好的格式，如HTML或PDF。它擁有豐富的外掛生態系統，可以幫助我們自動生成內容。我們的目標是建立一個如圖3.9所示的檔案首頁。

檔案目錄結構

在套件的根目錄下，有一個名為docs/的目錄，這裡存放著生成檔案所需的原始檔案和設定檔。py-pkgs-cookiecutter範本已經為我們建立了這個目錄和必要的檔案。下面是docs/目錄的結構：

pycounts
├── docs
│ ├── changelog.md
│ ├── conf.py
│ ├── contributing.md
│ ├── conduct.md
│ ├── example.ipynb
│ ├── index.md
│ ├── make.bat
│ ├── Makefile
│ └── requirements.txt

Makefile/make.bat：包含了使用sphinx構建檔案所需的命令，不需要修改。
requirements.txt：列出了在Read the Docs上託管檔案所需的依賴項。
conf.py：控制sphinx如何構建檔案的設定檔，目前不需要修改。
其他檔案構成了生成檔案的主要內容。

編寫檔案首頁

index.md檔案將成為我們檔案的首頁，相當於網站的首頁。在這裡，我們通常會提供套件的概述，並連結到其他相關檔案。以下是index.md的內容：

```{include} ../README.md

:maxdepth: 1
:hidden:
example.ipynb
changelog.md
contributing.md
conduct.md
autoapi/index


這裡使用了Markedly Structured Text（MyST）語法，它根據Markdown，但新增了一些與`sphinx`相容的語法選項。`{include}`語法用於包含其他檔案的內容，而`{toctree}`則定義了檔案目錄的結構。

#### 內容解密：
1.  `{include} ../README.md`：將根目錄下的`README.md`檔案內容包含到檔案中，實作了內容的重用。
2.  `:maxdepth: 1`：指定了目錄的最大深度為1，意味著只顯示第一級標題。
3.  `:hidden:`：使得目錄只在側邊欄顯示，而不在首頁上直接顯示。
4.  列出的檔案（如`example.ipynb`、`changelog.md`等）將被包含在檔案的目錄中。

### 建立API參考

最後一個在目錄中的檔案是“autoapi/index”，它是一個API參考表。使用`sphinx`的外掛，我們可以自動從程式碼中的docstring生成這個參考表。

## 使用 Sphinx 構建 Python 套件的檔案

在構建檔案之前，需要安裝和組態幾個 Sphinx 擴充套件。這些擴充套件可以提升檔案的外觀和使用者經驗。

### 安裝必要的 Sphinx 擴充套件

需要安裝以下擴充套件：

*   `myst-nb`：使 Sphinx 能夠解析 Markdown、MyST 和 Jupyter Notebook 檔案。
*   `sphinx-rtd-theme`：自定義主題，用於樣式化檔案的外觀。
*   `sphinx-autoapi`：解析原始碼和檔案字串以建立 API 參考表。
*   `sphinx.ext.napoleon`：使 Sphinx 能夠解析 numpydoc 風格的檔案字串。
*   `sphinx.ext.viewcode`：在 API 參考表中新增指向原始碼的連結。

使用 Poetry 管理專案時，可以透過以下命令安裝這些擴充套件作為開發依賴：

```bash
$ poetry add --dev myst-nb --python "^3.9"
$ poetry add --dev sphinx-autoapi sphinx-rtd-theme

內容解密：

poetry add --dev：將指定的套件安裝為開發依賴。
myst-nb --python "^3.9"：由於 myst-nb 的依賴套件 mdit-py-plugins 對 Python 版本有上限要求（<4.0），因此指定 Python 版本為 ^3.9（即大於等於 3.9 且小於 4.0）以確保相容性。
sphinx-autoapi 和 sphinx-rtd-theme：安裝用於生成 API 檔案和自定義主題的擴充套件。

組態 Sphinx 擴充套件

安裝完成後，需要在 conf.py 組態檔案中新增這些擴充套件並進行組態。py-pkgs-cookecutter 已經為我們完成了這一步，組態如下：

extensions = [
    "myst_nb",
    "autoapi.extension",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode"
]
autoapi_dirs = ["../src"]  # 解析 API 參考的原始碼位置
html_theme = "sphinx_rtd_theme"

內容解密：

extensions 列表：列出了要使用的 Sphinx 副檔名稱。
autoapi_dirs：指定了 sphinx-autoapi 要解析的原始碼目錄。
html_theme：設定了檔案的主題為 sphinx_rtd_theme。

構建檔案

組態完成後，可以導航到 docs/ 目錄並使用以下命令構建檔案：

$ cd docs
$ make html

內容解密：

cd docs：切換到包含檔案組態的目錄。
make html：使用 Sphinx 構建 HTML 格式的檔案。

構建成功後，HTML 檔案將位於 _build/html 目錄中。開啟 _build/html/index.html 可以預覽生成的檔案。

更新和維護檔案

對檔案進行重大更改後，建議刪除 _build/ 目錄並重新構建，以確保更新生效：

$ make clean html

內容解密：

make clean html：清除之前的構建結果並重新生成 HTML 檔案。

sphinx-autoapi 擴充套件會提取程式碼中的檔案字串並生成 API 參考表。sphinx.ext.viewcode 擴充套件則在 API 參考表中增加了指向原始碼的連結。

線上託管檔案

為了讓他人存取您的檔案，可以使用 Read the Docs 這類別免費服務。它會自動從您的 GitHub 倉函式庫構建和託管檔案。

提交更改到倉函式庫後，可以透過以下命令更新版本控制：

$ cd ..
$ git add README.md docs/example.ipynb
$ git commit -m "docs: updated readme and example"
$ git add src/pycounts/pycounts.py src/pycounts/plotting.py
$ git commit -m "docs: created docstrings for package functions"
$ git add pyproject.toml poetry.lock
$ git commit -m "build: added dev dependencies for docs"
$ git push

內容解密：

git add 和 git commit：將更改新增到暫存區並提交到本地倉函式庫。
git push：將本地提交推播到遠端倉函式庫。

Read the Docs 將自動檢測到更新並重新構建檔案，使其線上可用。

3.8 套件檔案託管

除了使用 Read the Docs 外，GitHub Pages 也是另一種流行的檔案託管服務。不過，GitHub Pages 預設並不支援自動建置檔案，因此我們在這裡選擇使用 Read the Docs。如果您仍想使用 GitHub Pages，可以考慮使用 ghp-import 套件，或是設定自動化的 GitHub Actions 工作流程，利用 peaceiris/actions-gh-pages 這個 action（我們將在第8章：持續整合和佈署中進一步討論 GitHub Actions）。

要使用 Read the Docs 託管檔案，請按照以下步驟進行：

造訪 https://readthedocs.org/，點選「Sign up」註冊。
選擇「Sign up with GitHub」進行註冊。
點選「Import a Project」。
點選「Import Manually」手動匯入專案。
填寫專案詳細資訊，包括：
- 您的套件名稱（例如：pycounts）。
- 您的套件在 GitHub 的儲存函式庫網址（例如：https://github.com/TomasBeuzen/pycounts）。
- 指定預設分支為 main。
點選「Next」，然後點選「Build version」。

完成上述步驟後，您的檔案應該會成功建置在 Read the Docs 上，您可以透過建置頁面上的「View Docs」按鈕來檢視。舉例來說，pycounts 的檔案現在可以在 https://pycounts.readthedocs.io/en/latest/ 上存取。每當您推播變更到 GitHub 儲存函式庫時，Read the Docs 都會自動重新建置您的檔案。

.readthedocs.yml 檔案的組態

py-pkgs-cookiecutter 為我們在 Python 套件的根目錄下建立了一個 .readthedocs.yml 檔案，其中包含了 Read the Docs 建置檔案所需的組態設定。它指定了要使用的 Python 版本，並告知 Read the Docs，我們的檔案需要 pycounts/docs/requirements.txt 中指定的額外套件才能正確生成。

玄貓 BlackCat

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。

Python套件檔案撰寫與託管

開發專業的Python套件檔案

編寫README檔案

README範例

使用方法

貢獻

授權

致謝

內容解密：

建立檔案網站

線上託管檔案

3.8 套件檔案編寫

3.8.1 檔案內容

使用 numpydoc 風格的 docstring

檔案內容解密：

3.8.2 建立 API 參考檔案

為什麼使用 sphinx？

3.8.3 建立使用範例

為什麼使用 Jupyter Notebooks？

建立 Jupyter Notebook 範例

3.8.4 建立檔案網站

使用 sphinx 自動執行 notebook

開發專業的Python套件檔案

為什麼需要檔案生成工具？

使用sphinx生成檔案

檔案目錄結構

編寫檔案首頁

內容解密：

組態 Sphinx 擴充套件

內容解密：

構建檔案

內容解密：

更新和維護檔案

內容解密：

線上託管檔案

內容解密：

3.8 套件檔案託管

.readthedocs.yml 檔案的組態

玄貓 BlackCat

使用`sphinx`生成檔案