- 安装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文档集。用法如下:
在这里,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文档。调用它像这样:
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文件