Sphinx Bootstrap Theme.
项目描述
此 Sphinx 主题 将 Bootstrap CSS / JavaScript框架与各种布局选项、层次菜单导航和移动友好响应式设计集成在一起。它是可配置的、可扩展的，并且可以使用任意数量的不同 Bootswatch CSS主题。
介绍和演示
以下帖子介绍了此主题并进行了讨论
2011年12月9日 - Sphinx Twitter Bootstrap Theme
2012年11月19日 - Sphinx Bootstrap Theme Updates - Mobile, Dropdowns, and More
2013年2月12日 - Sphinx Bootstrap Theme 0.1.6 - Bootstrap and Other Updates
2013年4月10日 - Sphinx Bootstrap Theme 0.2.0 - 现在支持 Bootswatch!
2013年8月9日 - Sphinx Bootstrap Theme 0.3.0 - Bootstrap v3 及更多功能！
主题在公共项目中的应用示例
Sphinx Bootstrap Theme：本项目使用主题选项 'bootswatch_theme': "sandstone" 使用“Sandstone” Bootswatch 主题。
Django Cloud Browser：用于浏览云数据存储（例如，亚马逊网络服务 S3）的 Django 可重用应用。
seaborn：一个统计数据分析库。
主题演示网站还包括一个 示例页面，展示了如何让 Sphinx 与 Bootstrap 一起良好地工作（也可以查看底层的 reStructuredText 的 示例源代码）。
安装
从 PyPI 安装相对直接
安装软件包
$ pip install sphinx_bootstrap_theme
编辑“conf.py”配置文件，将其指向 Bootstrap 主题
# At the top. import sphinx_bootstrap_theme # ... # Activate the theme. html_theme = 'bootstrap' html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
定制化
主题可以通过不同的方式定制（有的工作稍微多一些）。
主题选项
主题提供许多内置选项，可以通过编辑您的“conf.py”文件进行配置
# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
# Path should be relative to the ``_static`` files directory.
html_logo = "my_logo.png"
# Theme options are theme-specific and customize the look and feel of a
# theme further.
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
'navbar_title': "Demo",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "Site",
# A list of tuples containing pages or urls to link to.
# Valid tuples should be in the following forms:
# (name, page) # a link to a page
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
# (name, "http://example.com", True) # arbitrary absolute url
# Note the "1" or "True" value above as the third argument to indicate
# an arbitrary url.
'navbar_links': [
("Examples", "examples"),
("Link", "http://example.com", True),
],
# Render the next and previous page links in navbar. (Default: true)
'navbar_sidebarrel': True,
# Render the current pages TOC in the navbar. (Default: true)
'navbar_pagenav': True,
# Tab name for the current pages TOC. (Default: "Page")
'navbar_pagenav_name': "Page",
# Global TOC depth for "site" navbar tab. (Default: 1)
# Switching to -1 shows all levels.
'globaltoc_depth': 2,
# Include hidden TOCs in Site navbar?
#
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
# non-hidden ``toctree`` directives in the same page, or else the build
# will break.
#
# Values: "true" (default) or "false"
'globaltoc_includehidden': "true",
# HTML navbar class (Default: "navbar") to attach to <div> element.
# For black navbar, do "navbar navbar-inverse"
'navbar_class': "navbar navbar-inverse",
# Fix navigation bar to top of page?
# Values: "true" (default) or "false"
'navbar_fixed_top': "true",
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
'source_link_position': "nav",
# Bootswatch (http://bootswatch.com/) theme.
#
# Options are nothing (default) or the name of a valid theme
# such as "cosmo" or "sandstone".
#
# The set of valid themes depend on the version of Bootstrap
# that's used (the next config option).
#
# Currently, the supported themes are:
# - Bootstrap 2: https://bootswatch.com/2
# - Bootstrap 3: https://bootswatch.com/3
'bootswatch_theme': "united",
# Choose Bootstrap version.
# Values: "3" (default) or "2" (in quotes)
'bootstrap_version': "3",
}
关于导航栏标题的说明：如果您未指定主题选项 navbar_title，则“conf.py”中的 project 字符串将被使用。我们不使用 html_title 或 html_short_title 的值，因为这些默认情况下都包含版本字符串，而导航栏会将它们处理为不同。
Bootstrap 版本
主题支持通过 bootstrap_version 主题选项（“2”或“3”）的 Bootstrap v2.3.2 和 v3.3.7。以下是一些关于版本差异的说明
Bootstrap 3 已放弃对 子菜单 的支持，因此虽然本主题支持，但它们不会显示在网站或页面菜单中。
内部，“navbar.html” 是用于 Bootstrap v3 的 Sphinx 模板，而“navbar-2.html” 是用于 v2 的模板。
如果您不确定要选择哪个，请选择 Bootstrap 3。如果您遇到某些兼容性问题，那么尝试使用 Bootstrap 2。
扩展“layout.html”
作为一个更“亲自动手”的定制方法，您可以覆盖本 Sphinx 主题或其他主题中的任何模板。一个很好的更改候选是“layout.html”，它提供了大部分的外观和感觉。首先，查看主题提供的“layout.html”文件，并确定您需要覆盖什么。作为旁注，我们有一些特定于主题的增强，例如用于导航栏中额外内容的 navbarextra 模板块。
然后，创建自己的“_templates”目录和“layout.html”文件（假设您从“source”目录构建）
$ mkdir source/_templates $ touch source/_templates/layout.html
然后，配置您的“conf.py”
templates_path = ['_templates']
最后，编辑您的覆盖文件“source/_templates/layout.html”
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{# Add some extra stuff before and use existing with 'super()' call. #}
{% block footer %}
<h2>My footer of awesomeness.</h2>
{{ super() }}
{% endblock %}
添加自定义 CSS
或者，您可以添加自己的自定义静态媒体目录和一个 CSS 文件来覆盖样式，例如在演示中可能会是这样的
$ mkdir source/_static $ touch source/_static/my-styles.css
在新的文件“source/_static/my-styles.css”中添加任何适当的样式，例如一个加粗的背景颜色
footer {
background-color: red;
}
然后，在“conf.py”中编辑此行
html_static_path = ["_static"]
从那里取决于您使用的 Sphinx 版本
Sphinx <= 1.5
您需要配置如上所示的覆盖模板“source/_templates/layout.html”文件，但带有以下代码
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{# Custom CSS overrides #}
{% set css_files = css_files + ['_static/my-styles.css'] %}
Sphinx >= 1.6.1
在“conf.py”中添加一个setup函数，并将样式表路径添加到相对于静态路径的位置
def setup(app):
app.add_stylesheet("my-styles.css") # also can be a full URL
# app.add_stylesheet("ANOTHER.css")
# app.add_stylesheet("AND_ANOTHER.css")
主题说明
Sphinx
该主题将全局目录树、本地目录树、导航（上一页、下一页）和源链接都放置在顶部的Bootstrap导航栏中，同时在左侧还包含Sphinx搜索栏。
全局（网站范围内）的目录树是“网站”导航下拉菜单，它是整个网站toctree的可配置级别渲染。本地（页面级别）的目录树是“页面”导航下拉菜单，它是当前页面toc的多级渲染。
Bootstrap
该主题提供Bootstrap v2.x和v3.x，它们都依赖于jQuery v.1.9.x。由于Bootstrap想要的jQuery可能与Sphinx内部库使用的jQuery有很大不同，因此本主题通过noConflict()将库集成为$jqTheme。
您可以通过在Sphinx的“_static”目录中放置不同版本的文件来覆盖任何静态JS/CSS文件。
贡献
非常欢迎对这个项目的贡献。请确保演示网站可以干净地构建，并且看起来符合您的要求。本项目使用tox进行开发，一旦您安装了tox（例如，pip install tox），请将目录更改为sphinx-bootstrap-theme顶级目录。
构建文档：tox -e docs
验证文档中的HTML链接：tox -e linkcheck
验证代码风格：tox -e lint
使用此包进行开发的推荐方式是使用开发服务器。对存储库中本地文件所做的更改需要重新构建演示网站，而使用开发服务器将自动完成此过程。
在您的终端中，从顶级目录执行tox -e server。默认情况下，它将在端口8000上运行。如果此端口已被占用，则需要传递给底层sphinx-autobuild工具的参数，例如tox -e server -- -p 8080。在server和-p之间的--是必需的，这标志着tox的参数结束，之后的所有内容都会传递给sphinx-autobuild。
打开您选择的浏览器并访问http://127.0.0.1:8000/以查看服务器。
对存储库中的文件进行任何预期的编辑。服务器重新构建完成后，您可以刷新浏览器以查看更新。
完成时，请确保通过在运行tox -e server的终端中按ctrl+c来结束服务器。
打包
当推送标签形式为vX.Y.Z（以起始的v为标记）时，将使用tox -e dist构建发行版并将其自动上传到PyPI。在推送标签之前，应使用Test PyPI。除了tox之外，还应安装twine（pip install twine）。
# Build the distribution locally.
$ tox -e dist
# Attempt uploading to Test PyPI
$ twine upload -r testpypi dist/*在验证项目网址 Test PyPI 上的所有内容都符合预期 后，如果需要，还可以测试安装： pip install --index-url https://test.pypi.org/simple/ sphinx-bootstrap-theme
现在一切验证无误，我们准备发布。
在 sphinx_bootstrap_theme/__init__.py 中正确设置版本号。例如，对于发布 0.8.0，设置 __version__ = "0.8.0"，不包含结尾的 dev 修饰符。
如果需要，重新构建并上传到 Test PyPI。提交并推送更改后的版本号。标记此提交 git tag v0.8.0（注意前面的 v 是 CI/CD 所必需的），然后 git push --tags。这将启动官方发布并将其上传到 PyPI（有关更多信息，请参阅文件 .github/workflows/{package,github_pages}.yaml）。
发布推出后，更新版本号，以便从源安装的用户不会相信他们有一个官方发布。例如，设置 __version__ = "0.8.1.dev0"，提交并在线推送此“dev版本升级”。
许可证
Sphinx Bootstrap Theme 使用 MIT 许可证。
Bootstrap v2 使用 Apache 许可证 2.0。
Bootstrap v3.1.0+ 使用 MIT 许可证。
下载文件
下载适合您平台的文件。如果您不确定选择哪一个，请了解更多关于 安装软件包 的信息。
源分发
构建分发版本
sphinx-bootstrap-theme-0.8.1.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 683e3b735448dadd0149f76edecf95ff4bd9157787e9e77e0d048ca6f1d680df |
|
| MD5 | 705bb962d9ad21741f8b2efd6ebba2db |
|
| BLAKE2b-256 | 4c322c93f58beec8c85113fcbb3f1e213a1a773baaebfa064509a75d1d2f2320 |
sphinx_bootstrap_theme-0.8.1-py2.py3-none-any.whl的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 6ef36206c211846ea6cbdb45bc85645578e7c62d0a883361181708f8b6ea743b |
|
| MD5 | 1989a0eb13eec9c7c0444002b636cbfa |
|
| BLAKE2b-256 | 3a976b76343a692c6cf4481d3a900a0ee589499f8d642e7bcaf0192f9022305f |