Sphinx 配置

每个 Sphinx 项目必须包含一个 conf.py 配置文件，其中包含定制 Sphinx 输入和输出行为的所有配置。

配置文件在构建输出时作为 Python 代码执行，因此它可以执行任意复杂的代码。在配置时，如果没有特殊说明，值必须是字符串，并且默认值是空字符串。定义相对路径时，以配置文件所在的目录为源目录。

项目信息

project

项目名称

author

作者姓名。默认值是 unknown

copyright

版权声明

version

主要项目版本，用作 的替代品。

release

完整的项目版本，用作 的替代品。

一般配置项

source_suffix

定义源文件格式。该值是文件扩展名映射到文件类型的字典格式。例如:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

默认值是 {'.rst': 'restructuredtext'}

source_encoding

源文件的编码格式，默认值是 'utf-8-sig' 。

master_doc

文档的“目录树”文件，默认值是 'index' 。

exclude_patterns

当目录使用 * 匹配时，忽略定义的源文件列表。

示例:

• ['library/xml.rst'] – 忽略 library/xml.rst 文件(替换条目 unused_docs)

• ['library/xml'] – 忽略 library/xml 目录

• ['**/.svn'] – 忽略所有 .svn 目录

templates_path

包含自定义模板的路径列表，在构建时，模板路径中的文件会覆盖主题文件的同名文件。

rst_epilog

将一段 reStructuredText 文本添加到每个 rst 源文件的末尾，需要注意同时会添加到 index.rst 文件末尾。一个例子：

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

rst_prolog

将一段 reStructuredText 文本添加到每个 rst 源文件的开头，与 rst_epilog 相反。

highlight_language

设置代码高亮显示的默认语言，默认值是 'python' 。可以设置为 'none' 值不使用代码高亮。

HTML 输出选项

html_theme

HTML 输出时使用的 主题。

html_theme_options

所选主题外观的选项字典，这些是针对主题的，每个主题选项各不相同。

html_theme_path

包含自定义主题的路径列表，可以是子目录或 zip 文件。

html_style

用于 HTML 页面的样式表。文件必须存在于 _static 目录下，或者存放于 html_static_path 中定义的路径之一。默认值是所选主题给出的样式表。如果只想添加或覆盖主题样式表的一些内容，请使用 CSS @import 导入主题的样式表。

html_title

使用 Sphinx 模板生成的 HTML 文档标题。

html_short_title

一个更短的 HTML 文档标题。如果没有给出，它的默认值是 html_title。

html_baseurl

指向 HTML 文档根目录的 URL，文档部署时的链接网址。

html_logo

文档的标志，默认值是 None。值应该是不应超过 200 像素的图像文件包含路径的名称。

html_favicon

文档的 favicon，默认值是 None。现代浏览器使用它作为窗口和书签的图标。值应该是一个的图标文件（.ico）。

html_static_path

自定义静态文件的路径列表。在构建时，自定义路径的文件会覆盖主题文件的同名文件。出于安全原因，不会复制路径下的 dotfiles 文件。

html_extra_path

包含与文档无直接关系的额外文件的路径列表。在构建时，它们会覆盖任何同名的现有文件。

html_permalinks

是否为每个标题和描述环境添加“永久链接”，默认值是 True。

html_permalinks_icon

每个标题和描述环境的“永久链接”文本。默认值是一个段落符号 ¶。

html_copy_source

将 reST 源文件包含在 HTML 构建中。默认值是 True。

html_show_sourcelink

将指向 reST 源的链接添加到侧栏。默认值是 True。前提需要 html_copy_source 选项也为 True。

html_sourcelink_suffix

附加到源链接文件名的后缀名。默认是 '.txt' 。

html_file_suffix

生成的 HTML 文件的后缀名。默认值是 '.html' 。

html_link_suffix

生成 HTML 文件链接的后缀。默认值是 html_file_suffix。可以根据 Web 服务器设置不同值。

html_show_copyright

在 HTML 文档的页脚显示版权文本。默认是 True。

html_show_sphinx

在 HTML 文档的页脚显示“使用 Sphinx 创建”的文本。默认是 True。

html_output_encoding

输出 HTML 文件的编码。默认值是 'utf-8'。

html_secnumber_suffix

自动编号的后缀。默认值是 '. '。设置为 " " 将抑制编号上的最后一个点。

html_search_language

全文搜索索引的语言。默认使用 language 选择的全局语言。常用值 'en' 英语、 'zh' 中文。

epub输出的选项

epub_basename

epub 文件的基本名称。默认值是 project 名称。

epub_theme

构建 epub 输出的主题。由于默认主题未针对小屏幕进行优化，因此使用相同的主题进行 epub 输出是不明智的。

epub_theme_options

针对所选主题外观的选项字典。

epub_title

文件的标题。默认值是 project 选项。

epub_description

文件的描述。默认值是 'unknown' 。

epub_author

文件的作者。默认值是 author 选项。

epub_language

文件的语言。默认值是 language 选项或 'en'。

epub_publisher

文件的出版商。默认值是 author 选项。

epub_copyright

文件的版权。默认值是 copyright 选项。

epub_identifier

文档的标识符（ISBN 号）。默认值是 'unknown'。

epub_cover

文档封面。一个包含封面图像和 html 模板的文件名的元组。默认值是 ()

epub_cover = ('_static/cover.png', 'epub-cover.html')
# 可以只定义图片而不定义 html 模板
epub_cover = ('_static/cover.png', '')

epub_guide

文档的元数据 content.opf。一系列元组，包含 OPF 文档信息的 type、uri 和 title。有关详细信息，请参阅 http://idpf.org/epub 。

epub_exclude_files

在构建文档时不包含在 epub 文件中的文件列表。默认值是 []。

epub_tocdepth

文件中目录的深度。默认值是 3。深层嵌套的目录会难以导航。

epub_tocdup

是否在其嵌套的目录列表的开头再次插入目录。这样可以更轻松地导航到章节的顶部，但可能会让人感到困惑。默认值是 True 。

epub_max_image_width

指定图像的最大宽度。默认值是 0 （不执行缩放）。需要安装 Pillow 模块。

epub_show_urls

是否显示 URL 地址。支持以下值:

• 'inline' - 在括号中显示内联网址(默认)

• 'footnote' - 在脚注中显示网址

• 'none' - 不显示网址

配置文件示例

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another
# directory, add these directories to sys.path here. If the directory is
# relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ---------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
root_doc = 'index'

# General information about the project.
project = u'test'
copyright = u'2016, test'
author = u'test'

# The version info for the project you're documenting, acts as
# replacement for |version| and |release|, also used in various other
# places throughout the built documents.
#
# The short X.Y version.
version = u'test'
# The full version, including alpha/beta/rc tags.
release = u'test'

# The language for content autogenerated by Sphinx. Refer to
# documentation for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to
# some non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built
# documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False


# -- Options for HTML output -------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation
# for a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of
# a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this
# directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = u'test vtest'

# A shorter title for the navigation bar.  Default is the same
# as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the
# top of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a
# favicon of the docs.  This file should be a Windows icon file (.ico)
# being 16x16 or 32x32 pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets)
# here, relative to this directory. They are copied after the builtin
# static files, so a file named "default.css" will overwrite the builtin
# "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names
# to template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default
# is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is
# True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages
# will contain a <link> tag referring to it.  The value of this option
# must be the base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by
# default. 'ja' uses this config value. 'zh' user can custom change
# `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory)
# that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output -------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (root_doc, 'test.tex', u'test Documentation',
    u'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the
# top of the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output -------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (root_doc, 'test', u'test Documentation',
    [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -----------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (root_doc, 'test', u'test Documentation',
    author, 'test', 'One line description of project.',
    'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = False

# -- A random example ---------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')


autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']

配置实例

修改默认主题的样式

常用的 sphinx_rtd_theme 网页主题是以英文为基础设计的，在样式中定义了部分斜体字样式，不适用简体中文。可以使用自定义样式表（css 文件）覆盖原有样式文件。

找到主题的 theme.css 文件，复制到项目的 _static 目录下。

注意

路径名和文件名必须一致

例如，源文件路径为：sphinx_rtd_theme/static/css/theme.css，需要新建 css 目录，复制到项目后的路径为：project_name/_static/css/theme.css。

只需要复制修改的文件，不用将整个文件夹复制到 _static 目录下。

根据需要修改 theme.css 文件。

在 conf.py 配置文件中，添加 html_static_path = ['_static'] 配置选项。

重新构建项目，查看修改后的效果。