開始使用

設定您的專案和開發環境

在一個新目錄中，建立一個名為 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

備註

The installation method used above is described in more detail in PyPI 軟體包. For the rest of this tutorial, the instructions will assume a Python virtual environment.

If you executed these instructions correctly, you should have the Sphinx command line tools available. You can do a basic verification running this command:

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

If you see a similar output, you are on the right path!

建立文件配置

Then from the command line, run the following command:

(.venv) $ sphinx-quickstart docs

This will present to you a series of questions required to create the basic directory and configuration layout for your project inside the docs folder. To proceed, answer each question as follows:

  • > Separate source and build directories (y/n) [n]: Write "y" (without quotes) and press Enter.

  • > Project name: Write "Lumache" (without quotes) and press Enter.

  • > Author name(s): Write "Graziella" (without quotes) and press Enter.

  • > Project release []: Write "0.1" (without quotes) and press Enter.

  • > Project language [en]: Leave it empty (the default, English) and press Enter.

After the last question, you will see the new docs directory with the following content.

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

The purpose of each of these files is:

build/

An empty directory (for now) that will hold the rendered documentation.

make.bat 和 Makefile

Convenience scripts to simplify some common Sphinx operations, such as rendering the content.

source/conf.py

A Python script holding the configuration of the Sphinx project. It contains the project name and release you specified to sphinx-quickstart, as well as some extra configuration keys.

source/index.rst

The root document of the project, which serves as welcome page and contains the root of the "table of contents tree" (or toctree).

Thanks to this bootstrapping step, you already have everything needed to render the documentation as HTML for the first time. To do that, run this command:

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

And finally, open docs/build/html/index.html in your browser. You should see something like this:

Freshly created documentation of Lumache

Freshly created documentation of Lumache

There we go! You created your first HTML documentation using Sphinx. Now you can start customizing it.