※ 在 Windows-based 的作業系統要能具 Sphinx 的文檔寫作機制，務必要先安裝好 Python 的編譯環境。而且要對應 Sphinx 所對應的版本，例如 Sphinx 1.2b1 對應的是 Python 2.5 以上，那就不要安裝 3.x 或 低於 2.5 以下的版本，很可能 Sphinx 在編譯文檔時就會發生問題。
＊＊2013/06/15 ＊＊
Sphinx 可以安裝在 Python 3.3.2 的環境下。先至 Python Package page for distribute 下載最新版 distribute 套件，解壓縮後至該目錄執行：
C:>python distribute_setup.py |
就可以利用 easy_install 安裝 sphinx 套件。
安裝 Sphinx @Windows 環境
參考官方安裝－Windows: Install Python and Sphinx；另一份－在 Windows 7 環境安裝 Python 2.6.6。
- 安裝 Python : http://python.org/download/ (注意與 sphinx 搭配的 python 版本)
- 增加兩個 PATH 環境變數 (控制台 → 系統)： C:\Python27;C:\Python27\Scripts
- 命列列模式下，安裝 setup tools (如此安裝 3rd party 套件會更容易):
C:>python distribute_setup.py※ 如無法自動下載 distribute 套件，則至 https://pypi.python.org/pypi/Sphinx 下載該檔並解壓縮後，至該目錄執行上述安裝指令。
- 利用 easy_install 安裝 Sphinx (在命令列模式下執行 easy_install.exe)。
C:>easy_install -U sphinx
快速建立 Sphinx 預設文檔結構 (可視為每一份文檔的基礎框架)
官方主要參考文件：First Steps with Sphinx。
利用 sphinx-quickstart script 快速建立 Sphinx 基礎文檔 (以下操作，均於命令列模式下)。
- 先新增一資料夾：D:\docs，作為預設文檔存放位置。
D:\docs>sphinx-quickstart執行後，會列出許多問題供回答，絕大部分選預設即可。下列即是問題回應的範本。
Welcome to the Sphinx quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: docs You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/N) [n]: y Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: Demo Project > Author name(s): Kenming Wang Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 0.6 > Project release []: 0.6 The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/N) [n]: y > doctest: automatically test code snippets in doctest blocks (y/N) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: y > coverage: checks for documentation coverage (y/N) [n]: y > pngmath: include math, rendered as PNG images (y/N) [n]: > jsmath: include math, rendered in the browser by JSMath (y/N) [n]: > ifconfig: conditional inclusion of content based on config values (y/N) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (Y/n) [y]: > Create Windows command file? (Y/n) [y]: y
- 上述所有設定，可以透過 conf.py (位於 docs/source 目錄內)設定檔調整。如下列變數均可以重新設定：
- Change the version/release number by setting the version and release variables.
- Set the project name and author name.
- Setup a project logo.
- Set the default style to sphinx or default. Default is what the standard python docs use.
- 於 /docs 目錄下執行 make html 指令：
make html執行無誤後，會看到 ./build 目錄下會產生 HTML 格式的文檔。同理我們可以 make latex 產出 LaTex 或其他格式。
- 試著編輯位於 ./docs/source 目錄內的 index.rst (reStructured Text 標記語法)，然後再重新執行 make html 指令，再至 ./docs/build/html 目錄下查看 index.html 結果。
.. Demo_Project documentation master file, created by sphinx-quickstart on Wed May 29 22:03:05 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Demo_Project's documentation! ======================================== Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
＊＊2013/06/22 ＊＊
o sphinxcontrib-fulltoc extension：changes the HTML output to include a more detailed table of contents in the sidebar.
※ 其它參考資訊
o How to create a Sphinx based documentation for your project.
o Documenting Your Project Using Sphinx.
o Sphinx 初嘗。
o 寫最好的文檔：Sphinx + Read the Docs。