turingq-sphinx-theme 0.1.1

sphinx-book-theme with optional TuringQ company header and footer chrome for Sphinx docs

turingq-sphinx-theme

Sphinx HTML theme extending sphinx-book-theme with optional TuringQ company header/footer (static chrome, CSS/JS bundled in the wheel).

Use this package when algorithm or product teams build standalone Sphinx docs while keeping the same top bar and footer as the main DeepQuantum site.

Install

pip install turingq-sphinx-theme

Verify the theme (developers / before publish)

From a clone of this repo, install in editable mode and run the smoke script (uses sphinx-build or python -m sphinx.cmd.build):

cd turingq-sphinx-theme
python -m pip install -e .
./examples/smoke/verify.sh    # or: PYTHON=/path/to/venv/bin/python ./examples/smoke/verify.sh

See examples/smoke/README.md for manual checks and turingq_company_chrome: False experiments.

conf.py (minimal)

Sphinx discovers the theme via the sphinx.html_themes entry point and runs this package’s setup() (same pattern as sphinx-book-theme), which registers the theme path and injects custom.css、iframe-fullscreen-fallback.js (fullscreen tooltips / iframe behavior), then site-chrome.css / site-chrome.js when turingq_company_chrome is enabled. Do not duplicate those names under html_css_files / html_js_files.

Bundled custom.css does not include DeepQuantum-main-site-only CSS that hides PDF / extra source formats in the download dropdown when .ipynb is present—you get the theme default download list (.rst, .pdf, etc.) without extra hides.

html_theme = "turingq_sphinx_theme"

# Optional but recommended (matches upstream DeepQuantum docs): keep body/default mode aligned with forced light CSS.
html_context = {"default_mode": "light"}

html_theme_options = {
    # Default is True — company header/footer + chrome assets.
    "turingq_company_chrome": True,
    # Optional — override logo link & top navigation (defaults in turingq_sphinx_theme/defaults.py):
    # "turingq_logo_href": "https://example.org/",
    # "turingq_nav": [{"text": "Home", "url": "/", "external": False}],
    # Forward any sphinx-book / pydata options below, for example:
    # "repository_url": "https://github.com/you/your-repo",
}

You do not need to duplicate the theme module under extensions (unless your team explicitly prefers it; Sphinx will otherwise load setup() when the HTML theme resolves).

Disable company chrome (plain sphinx-book-theme look, minus our layout overrides):

html_theme_options = {"turingq_company_chrome": False}

Theme configuration switch

The option is declared in theme.conf as turingq_company_chrome and can be overridden from html_theme_options in conf.py.

Build and publish to PyPI（软件组标准流程）

算法侧要求：在本地开发与测试完成之后，使用社区通行的 Python 打包工具链生成 wheel/sdist，再上传到 PyPI——不要用手写非标脚本或未版本化的零散拷贝。

1. 前置检查

步骤	说明
自测	在本仓库根目录执行 ./examples/smoke/verify.sh（需已 pip install -e .，见上文「Verify the theme」），确认主题可正常构建 HTML。
版本号	新发布时请同步调高 pyproject.toml 的 project.version 与 turingq_sphinx_theme/__init__.__version__，二者须一致；否则轮子与 Sphinx 报告的版本会不一致。

2. 安装打包工具

pip install build twine

• build：按 pyproject.toml / PEP 517，在隔离环境中调用 setuptools 后端生成 dist/ 下的 .whl 与 源码发行包。
• twine：将 dist/ 中的制品上传到 PyPI（或配置的索引）。

3. 打包

在本目录 turingq-sphinx-theme/（包含 pyproject.toml 的一级目录）执行：

cd turingq-sphinx-theme
python -m build

成功后 dist/ 中应有当前版本的 wheel（*.whl）与 sdist（*.tar.gz）。

4. 发布到 PyPI

twine upload dist/*

等价写法（同一版本只有两个主文件时可显式列出）：

twine upload dist/turingq_sphinx_theme-*.whl dist/turingq_sphinx_theme-*.tar.gz

凭证（需在组织或个人账号就绪后再执行）：

• 推荐 PyPI API token：pypi-...
  可先配置 ~/.pypirc，或使用：TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-xxxx twine upload dist/*
• 或组织使用的 Trusted Publishing（如 CI 与 PyPI OIDC），按内部文档配置，不一定要本机 twine upload。

请勿将 token 写入仓库。首次也可先推到 TestPyPI 试安装：

twine upload --repository testpypi dist/*

Detailed technical documentation (Chinese)

Integration of the upstream DeepQuantum docs (project-local templates + _static) and architecture of this package (Sphinx entry points, inheritance, migrations): see TECHNICAL.md.

License

Apache-2.0 (same as parts of upstream assets originating from this repository).