- 安裝Sphinx
- www.python.org 下載python2|3並安裝，目前都內置pip管理，將目錄環境添加到path
- pip install sphinx 或者 https://pypi.python.org/pypi/Sphinx 可下載包
Sphinx Available builders
The builder’s “name” must be given to the -b command-line option ofsphinx-build to select a builder
class sphinx.builders.html.StandaloneHTMLBuilder
Its name is html.
class sphinx.builders.html.DirectoryHTMLBuilder
Its name is dirhtml.
class sphinx.builders.html.SingleFileHTMLBuilder
Its name is singlehtml.
class sphinx.builders.htmlhelp.HTMLHelpBuilder
Its name is htmlhelp.
class sphinx.builders.qthelp.QtHelpBuilder
Its name is qthelp.
class sphinx.builders.devhelp.DevhelpBuilder
Its name is devhelp.
class sphinx.builders.epub.EpubBuilder
Its name is epub.
class sphinx.builders.latex.LaTeXBuilder
Its name is latex.
class sphinx.builders.text.TextBuilder
Its name is text.
class sphinx.builders.manpage.ManualPageBuilder
Its name is man.
class sphinx.builders.texinfo.TexinfoBuilder
Its name is texinfo.
class sphinx.builders.html.SerializingHTMLBuilder
implementation
out_suffix
globalcontext_filename
searchindex_filename
class sphinx.builders.html.PickleHTMLBuilder
Its name is pickle
class sphinx.builders.html.JSONHTMLBuilder
Its name is json.
class sphinx.builders.gettext.MessageCatalogBuilder
Its name is gettext.
class sphinx.builders.changes.ChangesBuilder
Its name is changes.
class sphinx.builders.linkcheck.CheckExternalLinksBuilder
Its name is linkcheck.
詳情：http://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
===============
命令行用法
sphinx-build 腳本構建了一個Sphinx文檔集。用法如下:
$ sphinx-build [options] sourcedir builddir [filenames]
在這裏，sourcedir 是指 源目錄，builddir 是指你想指定的生成文檔的目錄。大部分時候，是不需要指定 filenames。
sphinx-build 腳本有如下的選項:
- -b buildername
-
最重要的選項: 它選擇生成器。常見的生成器如下：
- html
- 生成HTML頁面。這是默認生成器。
- dirhtml
- 生成HTML頁面，但是每個文件單獨一個目錄。如果web服務器提供服務，能夠生成漂亮的URLs(沒有 .html 後綴)。
- singlehtml
- 整個內容生成一個HTML頁面。
- htmlhelp, qthelp, devhelp, epub
- 生成HTML文件，包含了生成上述格式的文檔集合的其他信息。
- latex
- 生成可以被編譯成PDF文件的LaTeX源文件通過使用 pdflatex。
- man
- 生成UNIX操作系統的groff格式的手冊。
- texinfo
- 生成Texinfo文件，它能夠通過 makeinfo 處理成 Info 文件。
- text
- 生成純文本文件。
- gettext
- 生成gettext的風格的消息目錄（.pot 後綴的文件）。
- doctest
- 如果 doctest 激活，執行文件中所有的doctests。
- linkcheck
- 檢查所有的外部鏈接的完整性。
請參看 Available builders，裏面列出了Sphinx自身附帶的所有的生成器。用戶可以添加自己的生成器擴展。
- -a
-
如果給定，總是生成所有輸出文件。默認是隻生成新的和更改的源文件的輸出文件。（這可能並不適用於所有的生成器。）
- -E
-
不要使用已保存的 環境 （系統緩存所有交叉引用），會完全重新生成。默認是僅僅讀取和解析自上次運行後新的或者已更新的源文件。
- -d path
-
因爲Sphinx在生成輸出文件之前，必須讀取和解析所有的源文件，被解析過的源文件會被緩存爲”doctree pickles”。通常，這些緩存文件會被放入於生成目錄中的名爲 .doctrees 的文件夾裏；使用該選項可以選擇不同的緩存文件夾（所有生成器都可以共享doctrees文件夾）。
- -c path
-
使用給定的配置文件目錄，忽略源文件中的 conf.py 配置文件。值得注意的是配置文件中的其他文件以及路徑可能會跟配置文件目錄有關，所以也必須使用指定的路徑。
New in version 0.3.
- -C
-
不使用配置文件；使用 -D 選項後的配置值。
New in version 0.5.
- -D setting=value
-
覆蓋配置文件 conf.py 中一個配置值對。該值必須是一個字符串或者字典值。對於字典值，需要給吃鍵值對類似：-D latex_elements.docclass=scrartcl。對於布爾值，使用 0 或者 1。
Changed in version 0.6: The value can now be a dictionary value.
- -A name=value
-
在HTML模版中，把 value 賦給 name 。
New in version 0.5.
- -n
-
運行在嚴格模式。目前，這會對所有丟失的引用拋出警告。
- -N
-
禁止帶顏色的輸出。（Windows下任何的帶顏色的輸出都是無效的。）
- -q
-
不要在標準輸出上輸出任何東西，只給出標準錯誤的警告和錯誤。
- -Q
-
不要在標準輸出上輸出任何東西，也包括警告。只有錯誤被寫入標準錯誤。
- -w file
-
輸出除標準錯誤外的警告（和錯誤）到指定的文件。
- -W
-
把警告轉換成錯誤輸出。這就說構建會在第一個警告的時候停止，sphinx-build 會以錯誤狀態1退出。
- -P
-
（僅調試時有用。）構建時候，如果出現未處理的遺產，運行python調試器，pdb。
在命令行中，你可以在源目錄以及生成目錄後給出一個或者多個文件名。Sphinx 將會嘗試構建給出的這些文件的輸出（以及它們的依賴。）
Makefile選項
由 sphinx-quickstart 生成的 Makefile 和 make.bat 文件是隻使用了 sphinx-build 的 -b 和 -d 參數。 然而， 它們支持以下的變量（參數）來定製化：
- PAPER
-
latex_paper_size 的值。
- SPHINXBUILD
-
替代 sphinx-build 的命令。
- BUILDDIR
-
指定生成的目錄，而不是使用在 sphinx-quickstart 中選擇的路徑。
- SPHINXOPTS
-
sphinx-build 的附加選項。
調用sphinx-apidoc
sphinx-apidoc 能夠對一個python包生成完全的自動的API文檔。調用它像這樣:
$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
packagedir 是指生成文檔的包所在的路徑， outputdir 生成的文檔所存放的路徑。任何給定的 pathnames 是在生成過程中需要忽略的路徑名（[pathnames]裏的東西在生成文檔中是忽略的。）
sphinx-apidoc 有如下些選項:
- -o outputdir
-
給出生成的文檔所在的路徑。
- -f, --force
-
通常，sphinx-apidoc不會重新生成任何文件。使用這個選項強制重新生成所有的文件。
- -n, --dry-run
-
使用這個選項的話，不會有任何文件生成。（空運行，或者稱爲幹運行。）
- -s suffix
-
這個選項指定了輸出的文件的文件名後綴。默認情況下，後綴是 rst。
- -d maxdepth
-
如果存在內容表，設置內容表的最大深度。
- -T, --no-toc
-
這可以防止生成的表的內容文件 modules.rst。但是當 --full 給出的時候，本選項就不起作用了。
- -F, --full
-
此選項使得sphinx-apidoc創建一個完整的Sphinx項目，與 sphinx-quickstart 使用同樣的機制。大部分的配置值是設置成默認的值，但是你可以通過如下選項修改一些重要的配置值。
- -H project
-
設置項目名稱，使得生成到輸出的文件 (請見 project).
- -A author
-
設置作者名，使得生成到輸出的文件 (請見 copyright).
- -V version
-
設置項目版本，使得生成到輸出的文件 (請見 version).
=================
- 命令行 使用sphinx-quickstart 快速創建DOC項目
pass
- make htmlhelp
即可在DOC內創建build/htmlhelp 的源文件，需要系統安裝Microsoft HTML Help支持
Microsoft HTML Help Workshop https://msdn.microsoft.com/en-us/library/ms669985
同時生成 Microsoft的.chm文件