定制

Alabaster的行为和风格可以通过多种方式进行自定义：

• 可以通过您的配置各种模板级或非平凡样式的设置 conf.py 在里面 html_theme_options 见 主题选项 .

• 从Alabaster 0.7.8开始，您可以通过 custom stylesheet 。这适用于只需要少量CSS修改的更改。

  备注

  在0.7.8之前实现的一些主题选项更适合作为本地自定义样式表覆盖。因此：

  • 我们不再接受通过使用此功能更合适地解决的功能请求。

  • 在将来的向后不兼容版本中，我们可能会弃用其中一些选项；因此，我们强烈建议尽可能利用自定义样式表，即使下面提供了一个选项。

    • 如果有疑问，只需勾选 the built-in stylesheet's template 以查看您正在查看的选项是基本的变量插入还是更复杂的操作。)

自定义样式表

如果需要修改Alabaster的默认CSS样式，则可以按如下方式提供自定义CSS样式表，该方式未包含在下一节的主题选项中：

• 创建名为 custom.css 任何您喜欢的地方(通常 _static/ ，但这完全是约定)，其中包含您想要的对Alabaster中的CSS的覆盖 static/alabaster_css_t .

• 设置核心Sphinx选项 html_static_path 设置为该文件的路径或其所在的目录。

主题选项

Alabaster的主要配置路线是 html_theme_options 变量，设置在 conf.py 在睡觉沿线，例如：

html_theme_options = {
    'logo': 'logo.png',
    'github_user': 'sphinx-doc',
    'github_repo': 'alabaster',
}

以下小节详细介绍了可用的此类选项，包括有关行为的说明。可通过查看找到缺省值 theme.conf 直接去吧。

基础

与文本显示、徽标等相关的设置。

• body_text_align ：哪个CSS text-align 要用于正文文本的值(如果有)。

• canonical_url ： Deprecated ，请使用 html_baseurl 而是狮身人面像选项。如果设置，则用作 <link rel="canonical"> canonical URL 标题标签。

  备注

  该值必须以尾随的劈开结尾。

• description ：有关您的项目的文本格式回复信息，显示在徽标下面。

• description_font_style ：哪个CSS font-style 用于描述文本。

• fixed_sidebar ：使侧边栏“固定”或固定到位，以便页面主体滚动，但侧边栏保持可见。(仅适用于桌面窗口大小；移动视图不受影响。)

• logo ：相对路径(从 $PROJECT/_static/ )转换为徽标图像，该图像将出现在项目名称上方的左上角。

  • 如果 logo 未设置，则您的 project 名称设置(来自顶层Sphinx配置)将在文本标题中使用。这将保留从内部文档页面返回到您主页的链接。

• logo_name ：设置为 True 插入您的站点的 project 徽标图像下的名称作为文本，或转换为任何字符串以包括任意文本。如果您的徽标不包含项目名称本身，则非常有用。

• logo_text_align ：哪个CSS text-align 用于徽标文本的值(如果有。)

• page_width ：控制默认内容/页面宽度的CSS宽度说明符。

• sidebar_width ：控制默认边栏宽度的CSS宽度说明符。

• touch_icon ：图像的路径(与 logo ，相对于 $PROJECT/_static/ )用于iOS应用程序图标，用于通过Safari将页面保存到iOS设备的主屏幕。

服务链接和徽章

第三方服务(GitHub、Travis-CI等)和相关徽章或横幅。

• analytics_id ：设置为您的 Google Analytics ID(例如 UA-#######-## )以启用跟踪。

• badge_branch ：设置在Travis、CodeCov等徽章中使用哪个分支。

• codecov_button ： true ， false 或者是Github风格的 "account/repo" 字符串-用于显示 Codecov 侧边栏中的构建状态按钮。如果 true ，使用您的 github_(user|repo) 设置。

• donate_url ：通用/任意捐赠服务的url；导致显示基本的“捐赠”徽章/盾牌(来自链接到给定url的https://shields.io)。

• github_banner ： true 或 false -是否在页面右上角应用“在Github上分叉我”横幅。

  • 如果 true ，需要您设置 github_user 和 github_repo （见下文）。

  • 也可以提交字符串文件路径(与 logo ，相对于 $PROJECT/_static/ )用作横幅图像，而不是默认设置。

• github_button ： true 或 false -是否链接到您的Github。

  • 如果 true ，需要您设置 github_user 和 github_repo .

  • 此外，还有 github_type 和 github_count 选项，其行为如中所述 Github Buttons' documentation .

• github_repo ：用于 github_button 和 github_banner (请参见上文)；如果这两项都设置为，则不执行任何操作 false .

• github_user ：用于 github_button 和 github_banner (请参见上文)；如果这两项都设置为，则不执行任何操作 false .

• gittip_user / gratipay_user ： 已弃用 ，因为该服务不再运行。这些选项仍然存在(删除它们会破坏向后兼容性；当用户尝试设置不存在的选项时，会出现Sphinx错误)，但是它们不再执行任何操作。

• tidelift_url ：将此设置为您的 Tidelift 如果您想要在您的侧边栏中有一个“专业支持”部分，请使用项目URL。

  • 如果直接从Tidelift的站点复制URL，您可能需要更改 &utm_campaign=readme 到 &utm_campaign=docs .

• travis_button ： true ， false 或者是Github风格的 "account/repo" 字符串-用于显示 Travis-CI 侧边栏中的“构建状态”按钮。如果 true ，使用您的 github_(user|repo) 设置。

非服务侧边栏控件

与服务链接没有直接关系的侧栏相关选项。

• extra_nav_links ：字典将链接名称映射到链接目标；这些将添加到主边栏导航下方的UL中(前提是您已启用 navigation.html 通过 html_sidebars 选项；见 安装 。)对于Sphinx文档树外部的静电链接非常有用。

• show_related ：控制侧栏“下一个/上一个/相关”辅助导航元素是隐藏还是显示的布尔值。默认为 false 因为在许多网站上，这些元素是多余的。

  备注

  这与 show_relbars 页眉/页脚选项中的设置；这两个可视组件是正交的，可以彼此独立地启用/禁用。

• sidebar_collapse ：确定是否所有符合以下条件的目录条目都是布尔值

  不是当前页的祖先，则会折叠。您可以在Sphinx toctree中阅读有关这方面的更多信息 docs 。

• sidebar_includehidden ：确定TOC侧栏是否应该包含隐藏的Sphinx toctree元素的布尔值。默认为 true 所以你可以使用 :hidden: 在你的索引页面的根目录树中&避免在你的登录页面上有2倍的导航副本。

页眉/页脚选项

哪些元素应出现在页眉和/或页脚中，或对其进行修改。

• show_powered_by ：布尔值控制 Powered by Sphinx N.N.N. & Alabaster M.M.M 页脚的一节。什么时候 true ，显示在版权信息旁边；当 false ，是隐藏的。

  自 0.17.14 版本弃用: 集 html_show_sphinx 至 True 或 False 在……里面 conf.py 取而代之的是。

• show_relbars ： true 或 false -用于显示 next 和 previous 主页内容上方和下方的链接。如果只想显示一个，则可以通过 show_relbar_top 和 show_relbar_bottom 设置。

  备注

  这与 show_related 在侧栏控件选项中找到的设置，用于控制仅限侧栏的下一个/上一个链接。

样式颜色

这些应该是完全限定的CSS颜色说明符，例如 #004B6B 或 #444 。列表中的前几项是用作其他许多项的默认值的“全局”颜色；更新这些项以对配色方案进行彻底更改。可以根据需要使用更精细的设置来覆盖。

• anchor ：节锚链接的前景色(将鼠标悬停在页面节标题上时显示的‘段落’符号。)

• anchor_hover_bg ：背景颜色 anchor 文本。

• anchor_hover_fg ：鼠标悬停在节锚点链接上时的前景色(如上所述)。

• body_text ：主要内容文本。

• code_highlight ：使用时突出显示的颜色 :emphasize-lines: 代号挡路。

• footer_text ：页脚文本(包括链接。)

• footnote_bg ：脚注块的背景。

• footnote_border ：相同的边框。

• gray_1 ：深灰色。

• gray_2 ：浅灰色。

• gray_3 ：中灰色。

• link_hover ：主体链接，悬停。

• link ：未悬停的躯干链接。

• narrow_sidebar_bg ：当窄窗口将“侧边栏”强制放到页面底部时，“侧边栏”的背景。

• narrow_sidebar_fg ：相同的文本颜色。

• narrow_sidebar_link ：链接颜色相同。

• note_bg ：背景： .. note:: 阻碍。

• note_border ：相同的边框。

• pink_1 ：浅粉色。

• pink_2 ：中粉色。

• pre_bg ：预格式化文本块的背景(包括代码段。)

• relbar_border ：钢筋夹持之间的边框颜色 next 和 previous 链接，以及睡觉的页面内容。

• seealso_bg ：背景： .. seealso:: 阻碍。

• seealso_border ：相同的边框。

• sidebar_header ：侧栏标题。

• sidebar_hr ：侧栏水平标尺分隔符的颜色。

• sidebar_link ：侧边栏链接(没有悬停变体。)适用于页眉和文本链接。

• sidebar_list ：侧栏列表项目符号和未链接文本的前景色。

• sidebar_link_underscore ：侧栏链接的下划线(严格地说是底部边框)。

• sidebar_search_button ：搜索字段的“Go”按钮的背景色。

• sidebar_text ：侧栏段落文本。

• warn_bg ：背景： .. warn:: 阻碍。

• warn_border ：相同的边框。

字体

• caption_font_size ：字幕挡路文本的字体大小。

• caption_font_family ：字幕挡路文本的字体系列。

• code_font_size ：代码挡路文本的字体大小。

• code_font_family ：字体家族代码挡路文字。默认为 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace .

• font_family ：正文文本的字体系列。

• font_size ：正文文本的字体大小。

• head_font_family ：标题的字体系列。默认为 'Garamond', 'Georgia', serif .