JupyterHub文档主题

基于PyData Sphinx主题构建的轻量级主题，用于JupyterHub社区。它对pydata-sphinx-theme进行了最小的修改，以标准化样式和顶栏，该顶栏可以用于所有JupyterHub文档。

此主题设置的默认值

此主题设置了一些默认值，以标准化JupyterHub文档的外观和感觉。

If there are other standard features/customizations that would be helpful across the JupyterHub team documentation, we can probably add it here so please open an issue to discuss.

以下是一个简要总结

样式

• 将主要颜色设置为略暗的“Jupyter橙色”
• 从标题中移除主要颜色，使它们加粗以更加醒目
• 将标题链接对齐到左侧

标志和品牌

• 添加浅色/深色模式的 JupyterHub 标志
• 添加 favicon
• 添加我们的 Discourse、Team Compass 和 Jupyter.org 的图标链接

扩展

• sphinx-copybutton 用于我们的代码单元格中的复制按钮。
• sphinxext-opengraph 用于 OpenGraph 协议元数据。 site_url 将通过 CI/CD 中的 ReadTheDocs 或 GitHub Actions 环境变量自动检测。

如何使用此主题

按照以下步骤操作

1. 将此主题添加到存储库的 pip 安装需求中。目前，将其指向 main 分支，如下所示

   # in requirements.txt
   git+https://github.com/jupyterhub/jupyterhub-sphinx-theme
   

   或本地安装

   $ pip install git+https://github.com/jupyterhub/jupyterhub-sphinx-theme
   

2. 通过编辑 conf.py 配置来配置 Sphinx 文档使用此主题

   :caption: conf.py
   
   html_theme = "jupyterhub_sphinx_theme"
   

3. 将其添加到主题的扩展中

   :caption: conf.py
   
   extensions = [
      "jupyterhub_sphinx_theme"
   ]
   

在此基础上进行自定义

您可以在默认设置上进一步自定义。请参阅 PyData 主题文档 以了解您可以做什么。

一般来说，此主题仅设置默认值，您可以覆盖任何您喜欢的。

开发者文档

主题构建系统

此主题使用 sphinx-theme-builder 工具，这是一个自动编译 Sphinx 主题资产的辅助工具。这将下载 NodeJS 的本地副本并使用 package.json 中指定的环境构建主题的资产。

主题结构

此主题遵循 sphinx-theme-builder 文件系统布局。

本地构建主题

您可以为预览构建此主题的文档。在存储库中构建文档的最简单方法是使用 nox 自动化工具，这是一个用于快速构建环境和在其中运行命令的工具。这确保了您的环境具有构建文档所需的所有依赖项。

为此，请按照以下步骤操作

1. 安装 nox

   $ pip install nox
   

2. 构建文档

   $ nox -s docs
   

这应在 .nox 文件夹中创建一个本地环境，构建文档（如 noxfile.py 配置中指定），输出将在 docs/_build/html 中。

要构建当您更新本地文件时更新的实时文档，请运行以下命令

$ nox -s docs-live

发布版本

请参阅 RELEASE.md 中的说明