開始使用¶

設定您的專案與開發環境¶

在新的目錄中，建立一個名為 README.rst 的檔案，內容如下。

README.rst¶

Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

現在是建立 Python 虛擬環境並安裝必要工具的好時機。為此，開啟命令列終端機，cd 到您剛建立的目錄中，並執行以下命令

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

注意

上面使用的安裝方法在 PyPI 套件中有更詳細的說明。在本教學的其餘部分，說明將假設使用 Python 虛擬環境。

如果您正確執行了這些指示，您應該可以使用 Sphinx 命令列工具。您可以執行以下命令進行基本驗證

(.venv) $ sphinx-build --version
sphinx-build 4.0.2

如果您看到類似的輸出，那就表示您走在正確的道路上！

然後從命令列執行以下命令

(.venv) $ sphinx-quickstart docs

這將向您顯示一系列問題，這些問題是為了在 docs 資料夾中為您的專案建立基本目錄和設定配置。要繼續，請按如下方式回答每個問題

> Separate source and build directories (y/n) [n]：輸入 “y”（不含引號）並按下 Enter 鍵。
> Project name：輸入 “Lumache”（不含引號）並按下 Enter 鍵。
> Author name(s)：輸入 “Graziella”（不含引號）並按下 Enter 鍵。
> Project release []：輸入 “0.1”（不含引號）並按下 Enter 鍵。
> Project language [en]：保持空白（預設為英文）並按下 Enter 鍵。

在最後一個問題之後，您將看到新的 docs 目錄，其內容如下。

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

這些檔案各自的用途是

build/: 一個空的目錄（目前），將用於存放呈現的文件。
make.bat 和 Makefile: 方便的腳本，用於簡化一些常見的 Sphinx 操作，例如呈現內容。
source/conf.py: 一個 Python 腳本，用於保存 Sphinx 專案的設定。它包含您在 sphinx-quickstart 中指定的專案名稱和版本，以及一些額外的設定鍵。
source/index.rst: 專案的根文件，作為歡迎頁面，並包含「目錄樹」（或 toctree）的根。

由於這個引導步驟，您已經擁有首次將文件呈現為 HTML 所需的一切。要執行此操作，請執行以下命令

(.venv) $ sphinx-build -M html docs/source/ docs/build/

最後，在瀏覽器中開啟 docs/build/html/index.html。您應該會看到類似這樣的內容

完成了！您已經使用 Sphinx 建立了您的第一個 HTML 文件。現在您可以開始自訂它。