Metadata-Version: 2.4
Name: turingq-sphinx-theme
Version: 0.1.0
Summary: sphinx-book-theme with optional TuringQ company header and footer chrome for Sphinx docs
Author: TuringQ
License-Expression: Apache-2.0
Project-URL: Documentation, https://deepquantum.readthedocs.io/
Project-URL: Repository, https://github.com/TuringQ/deepquantum
Keywords: sphinx,sphinx-extension,sphinx-theme,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Framework :: Sphinx :: Theme
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sphinx>=7
Requires-Dist: sphinx-book-theme>=1.0
Dynamic: license-file

# turingq-sphinx-theme

Sphinx HTML theme extending [sphinx-book-theme](https://sphinx-book.readthedocs.io/) 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

```bash
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`):

```bash
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`](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.

```python
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):

```python
html_theme_options = {"turingq_company_chrome": False}
```

## Theme configuration switch

The option is declared in [`theme.conf`](turingq_sphinx_theme/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. 安装打包工具

```bash
pip install build twine
```

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

### 3. 打包

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

```bash
cd turingq-sphinx-theme
python -m build
```

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

### 4. 发布到 PyPI

```bash
twine upload dist/*
```

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

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

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

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

请勿将 token 写入仓库。**首次**也可先推到 [**TestPyPI**](https://test.pypi.org/) 试安装：

```bash
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](./TECHNICAL.md)**.

## License

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