# 使用 python Sphinx建立文件 （Windows）

這份指南將帶你一步步完成在 Windows 環境下使用 [Sphinx](https://www.sphinx-doc.org/) 建立文件的流程。

## 1. 安裝 Sphinx

### 在conda環境下安裝py310

conda create -n docs python=3.10
conda activate docs

### 安裝 Python 依賴項
製作 `requirements.txt` 文件

alabaster==1.0.0
babel==2.17.0
beautifulsoup4==4.13.4
certifi==2025.4.26
charset-normalizer==3.4.2
colorama==0.4.6
docutils==0.21.2
furo==2024.8.6
idna==3.10
imagesize==1.4.1
Jinja2==3.1.6
markdown-it-py==3.0.0
MarkupSafe==3.0.2
mdit-py-plugins==0.4.2
mdurl==0.1.2
myst-parser==4.0.1
packaging==25.0
Pygments==2.19.1
PyYAML==6.0.2
requests==2.32.3
snowballstemmer==3.0.0.1
soupsieve==2.7
Sphinx==8.1.3
sphinx-basic-ng==1.0.0b2
sphinxcontrib-applehelp==2.0.0
sphinxcontrib-devhelp==2.0.0
sphinxcontrib-htmlhelp==2.1.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==2.0.0
sphinxcontrib-serializinghtml==2.0.0
tomli==2.2.1
typing_extensions==4.13.2
urllib3==2.4.0

在conda環境中根據 `requirements.txt` 安裝依賴項

pip install -r requirements.txt

## 2. 建立 Sphinx 專案

python -m sphinx.cmd.quickstart

請依照提示輸入以下資訊：

* 專案名稱
* 作者名稱
* 語言（例如：`zh_TW` 或 `en`）
* 是否建立 `makefile` 或 `batch file`（建議選擇 `yes`）

這將會建立以下資料夾與檔案：

.
├── build/
├── source/
│   ├── conf.py        ← 設定檔
│   ├── index.rst      ← 首頁文件
├── Makefile
├── make.bat

## 3. 生成 HTML 文件

在專案根目錄執行：

python -m sphinx source build/html

# 或者可使用完整build command
python -m sphinx.cmd.build -M html ./source ./build --fail-on-warning


輸出結果會位於 `build/html/` 目錄下，開啟 `index.html` 即可瀏覽文件。


## 4. 生成 PDF 文件（LaTeX）

若需要輸出 PDF 文件（需安裝額外工具）：

### 安裝工具
#### 工具1：**[MiKTeX](https://miktex.org/download)**

Windows LaTeX 發行版
安裝後，使用「MiKTeX Console」下載 `latexmk` 套件。

#### 更新套件

##### 使用`where latexmk`確認安裝結果

#### 工具2：**[Strawberry Perl](https://strawberryperl.com/)**
> LaTeX 編譯過程需使用 Perl

進入[官網](https://strawberryperl.com/)下載

安裝檔案

>[!Tip]
>安裝完成後記得將IDE或VSCode關閉，讓Terminal可以抓到工具位置

### 生成 PDF

python -m sphinx.cmd.build -M latexpdf source build

可以生成一份挺完整的文件

## 5. 總結

| 步驟 | 說明 |
| -------- | ------------------------------------ |
| Conda 環境 | 使用 Python 3.10 建立獨立環境 |
| 安裝套件 | 通過`requirements.txt` 安裝 `sphinx`, `myst-parser`, `furo` 等套件|
| 快速初始化 | 使用 `sphinx-quickstart` 建立結構 | |
| 輸出 HTML | `python -m sphinx source build/html` |
| 輸出 PDF | 安裝 LaTeX 與 Perl， `python -m sphinx.cmd.build -M latexpdf source build` |

## 相關資源參考
- [sphinx .. toctree::](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-option-code-block-lineno-start)