Sphinx 主题用于 Airflow

Sphinx 主题用于 Apache Airflow 文档。

从源安装

为了开始使用此主题，请按照以下说明操作。

1. 确保 python 命令执行 Python3 解释器。如果需要，请使用虚拟环境

   mkvirtualenv -p python3 <name_of_environment>
   

2. 为了使主题中的JavaScript和CSS代码可用，请在根目录下运行以下命令：

   ./site.sh build-site && ./site.sh prepare-theme
   

3. 要安装所需的Python包，请在 <ROOT DIRECTORY>/sphinx_airflow_theme 中运行：

   pip install -e .
   

4. 要启动示例文档页面，请在 <ROOT DIRECTORY>/sphinx_airflow_theme/demo 中运行：

   ./docs.sh build && ./docs.sh preview
   

使用Sphinx主题更改生成Airflow文档

如果您对Sphinx主题进行了某些修改，并想生成Airflow文档以检查最终结果，请按照以下步骤操作：

1. 在 airflow-site 存储库中构建Airflow网站

   ./site.sh build-site
   

2. 将Sphinx主题打包成 whl 文件

   cd ./sphinx_airflow_theme
   python3 setup.py sdist bdist_wheel
   

3. (可选) 再次检查您的Sphinx主题修改是否已包含在 whl 文件中

   pip install wheel
   wheel unpack ./sphinx_airflow_theme-0.0.11-py3-none-any.whl
   

4. 将 whl 文件复制到 airflow 存储库中的 files 目录

   cp ./sphinx_airflow_theme-0.0.11-py3-none-any.whl ${AIRFLOW_REPO}/files/
   

5. 在 airflow 存储库中，初始化一个新的breeze环境

   breeze
   

6. 在breeze容器中，安装主题后再生成文档

   pip install /files/sphinx_airflow_theme-0.0.11-py3-none-any.whl --force-reinstall
   # Generate Airflow documentation only. If you need to generate the whole documentation (all providers),
   # you can do it using `/opt/airflow/scripts/in_container/run_docs_build.sh`. It takes longer to execute.
   /opt/airflow/scripts/in_container/run_docs_build.sh --package-filter apache-airflow
   

7. 验证生成的文档是否正确，并包含您的修改。文档生成在 docs/_build/docs/ 中。如果您仅生成了Airflow文档，您可以在 docs/_build/docs/apache-airflow/latest/ 中检查结果。

安装开发版本

要安装主题的最新开发版本，请运行：

THEME_VERSION="$(curl -s https://api.github.com/repos/apache/airflow-site/releases/latest | grep '"tag_name":' | cut -d '"' -f 4)"
pip install "https://github.com/apache/airflow-site/releases/download/${THEME_VERSION}/sphinx_airflow_theme-${THEME_VERSION}-py3-none-any.whl"

您的PR的Python包作为GitHub Actions中CI构建后的可下载工件提供。

配置

该主题支持在项目的 conf.py 中的 html_theme_options 字典下的以下配置选项：

navbar_links

应在页面顶部的导航栏中可用的链接列表。项目顺序不会改变。

示例值

html_theme_options = {
    'navbar_links': [
        {'href': '/docs/', 'text': 'Documentation'}
    ]
}

(这是默认值)

hide_website_buttons

如果 True，则将隐藏指向此主题页面的同一域名上的所有链接（例如，/community/）。

示例值

html_theme_options = {
  'hide_website_buttons': False,
}

sidebar_collapse

sidebar_includehidden

控制侧边栏中的目录显示。有关更多信息，请参阅 https://sphinx-doc.cn/en/master/templating.html#toctree

主题源文件

• <ROOT DIRECTORY>/sphinx_airflow_theme/sphinx_airflow_theme - HTML文件
• <ROOT DIRECTORY>/landing-pages/site/assets/scss - SCSS文件
• <ROOT DIRECTORY>/landing-pages/src/js - Javascript文件。如果您创建了新的JS文件，请确保将其包括在 `/landing-pages/src/docs-index.js` 中