使用 Sphinx 撰寫專案文件的第一步

建置您的 HTML 文件

sphinx-quickstart 建立的 index.rst 檔案已經有一些內容，它會被渲染成您 HTML 文件的前頁。它是用 reStructuredText 寫成的，這是一種功能強大的標記語言。

依照以下方式修改檔案

docs/source/index.rst
Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

這展示了 reStructuredText 語法的幾個功能，包括

  • 使用 === 底線的章節標題，

  • 兩個 行內標記 的範例：**strong emphasis** (通常是粗體) 和 *emphasis* (通常是斜體)，

  • 一個行內外部連結，

  • 以及一個 note 提示框 (可用的 指令 之一)

現在要使用新內容渲染它，您可以像之前一樣使用 sphinx-build 命令，或利用以下方便的腳本

(.venv) $ cd docs
(.venv) $ make html

執行此命令後，您將看到 index.html 反映了新的變更！

以其他格式建置您的文件

除了 HTML 之外，Sphinx 還支援多種格式，包括 PDF、EPUB、以及更多格式。例如，若要以 EPUB 格式建置您的文件，請從 docs 目錄執行此命令

(.venv) $ make epub

之後，您將在 docs/build/epub/ 下看到與電子書對應的檔案。您可以使用與 EPUB 相容的電子書閱讀器 (例如 Calibre) 開啟 Lumache.epub，或在網頁瀏覽器上預覽 index.xhtml。

注意

若要快速顯示可能的輸出格式的完整列表，以及一些額外有用的命令，您可以執行 make help。

每種輸出格式都有一些特定的設定選項可以調整，包括 EPUB。例如，epub_show_urls 的預設值為 inline，這表示預設情況下，URL 會顯示在對應連結的正後方，並以括號括起來。您可以透過在 conf.py 的末尾新增以下程式碼來變更該行為

# EPUB options
epub_show_urls = 'footnote'

使用此設定值，並在再次執行 make epub 後，您會注意到 URL 現在以註腳形式出現，這樣可以避免使文字雜亂。太棒了！請繼續閱讀以探索其他客製化 Sphinx 的方式。

注意

使用 Sphinx 產生 PDF 可以透過執行 make latexpdf 來完成，前提是系統已安裝可運作的 LaTeX，如 sphinx.builders.latex.LaTeXBuilder 的文件中所述。儘管這完全可行，但此類安裝通常很大，而且一般來說，LaTeX 在某些情況下需要仔細設定，因此 PDF 產生超出本教學課程的範圍。