chore: update config for docs

docs/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# 文档贡献指南 | Contributing docs <!-- omit from toc -->
+
+- [tl;dr](#tldr)
+- [前置条件](#前置条件)
+- [环境准备](#环境准备)
+- [构建文档](#构建文档)
+- [预览文档](#预览文档)
+- [文件清理](#文件清理)
+- [报告问题](#报告问题)
+
+## tl;dr
+
+```sh
+python -m pip install -r requirements.txt
+secretflow-doctools build --lang zh_CN
+secretflow-doctools preview
+```
+
+> [!TIP]
+>
+> 下文的示例命令建议在[本目录 (docs)](./) 下执行。
+
+## 前置条件
+
+本项目使用 [Sphinx] 作为文档框架。你需要：
+
+- [Python] >= 3.10
+
+## 环境准备
+
+执行：
+
+```sh
+python -m pip install -r requirements.txt
+```
+
+这将会：
+
+- 安装[文档构建所需要的依赖](./requirements.txt)
+
+> [!TIP]
+>
+> 你也可以使用 [uv], [mamba] 等其他的依赖管理工具。
+
+## 构建文档
+
+[`secretflow-doctools`] 是针对隐语项目文档构建的辅助工具，它协助开发者在本地构建并
+且[预览](#预览文档)文档。
+
+执行：
+
+```sh
+secretflow-doctools build --lang en --lang zh_CN
+```
+
+这将会构建英文版 `en` 以及中文版 `zh_CN` 文档。
+
+如果一切正常，你应当能看到以下输出：
+
+```log
+SUCCESS  to preview, run: secretflow-doctools preview -c .
+```
+
+> [!TIP]
+>
+> 如果提示 `secretflow-doctools` 命令未找到，你可能没有执行 `source .venv/bin/activate`
+> 以激活正确的 Python 环境；请参考[环境准备](#环境准备)中的指引。
+
+如果想要只构建某个语言的文档，可以调整 `--lang` 选项。
+
+## 预览文档
+
+工具提供了本地预览的能力，帮助开发者验证文档在**发布到[隐语官网][website]后的显示效
+果**。
+
+执行：
+
+```sh
+secretflow-doctools preview
+```
+
+这将会在本地启动一个预览服务器。你应当能看到以下输出：
+
+```
+ * Running on http://127.0.0.1:5000
+```
+
+用浏览器访问 <http://127.0.0.1:5000> （或其它端口号），你应当能看到类似下图的页面，其中
+将会列出在本地构建好的文档版本：
+
+<figure>
+  <img src="_static/CONTRIBUTING/preview-sitemap.png" alt="the sitemap page">
+</figure>
+
+点击一个版本即可打开对应预览，你应当能看到类似下图的页面：
+
+<figure>
+  <img src="_static/CONTRIBUTING/preview-content.png" alt="the content page">
+</figure>
+
+> [!TIP]
+>
+> 你可以保持预览服务器一直开启：在重新构建文档后，刷新页面即可看到更新的内容。
+
+## 文件清理
+
+以上流程会产生额外的临时文件，这些文件全部位于 [\_build](./_build/) 目录下。如果需要清理
+，可以执行：
+
+```sh
+secretflow-doctools clean
+```
+
+## 报告问题
+
+如果在以上过程中遇到报错、预览无法显示等问题，可以提交问题到
+<https://github.com/secretflow/doctools/issues>。
+
+文档内容及本项目代码的相关问题请提交到本项目的 Issues 中。
+
+> [!NOTE]
+>
+> 为协助排查问题，你可以设置 `LOGURU_LEVEL=DEBUG` 环境变量来让文档工具输出更多日志。
+>
+> `secretflow-doctools` 会调用其他工具，在 `LOGURU_LEVEL=DEBUG` 时，日志会在每个步骤打印
+> 完整的命令行指令：
+>
+> |                                           |                  |
+> | :---------------------------------------- | :--------------- |
+> | `secretflow-doctools build`               | [`sphinx-build`] |
+> | `secretflow-doctools update-translations` | [`sphinx-intl`]  |
+
+[`secretflow-doctools`]: https://github.com/secretflow/doctools
+[`sphinx-apidoc`]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
+[`sphinx-build`]: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+[`sphinx-intl`]: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
+[gettext-po]: https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
+[gettext]: https://www.gnu.org/software/gettext/
+[mamba]: https://mamba.readthedocs.io/en/latest/
+[Poedit]: https://poedit.net/
+[Python]: https://www.python.org/
+[Sphinx]: https://www.sphinx-doc.org/en/master/tutorial/index.html
+[uv]: https://docs.astral.sh/uv/
+[venv]: https://docs.python.org/3/library/venv.html
+[website]: https://www.secretflow.org.cn/

docs/Makefile

@@ -1,20 +1,25 @@
-# Minimal makefile for Sphinx documentation
+# Copyright 2025 Ant Group Co., Ltd.
 #
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: build
+build:
+	secretflow-doctools build --lang zh_CN
 
-.PHONY: help Makefile
+.PHONY: preview
+preview:
+	secretflow-doctools preview
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: clean
+clean:
+	secretflow-doctools clean

docs/conf.py

@@ -1,86 +1,59 @@
-# Configuration file for the Sphinx documentation builder.
+# Copyright 2025 Ant Group Co., Ltd.
 #
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-project = "Interconnection"
-copyright = "2022-2024 Ant Group Co., Ltd"
-author = "Secretflow Authors"
-
-# -- Multi-language config ---------------------------------------------------
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = "zh_CN"
-
-locale_dirs = ["locale/"]  # path is example but recommended.
-gettext_compact = False  # optional.
-gettext_uuid = False  # optional.
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+project = "Interconnection"
 
 extensions = [
+    "secretflow_doctools",
+    # API docs
+    # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
     "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
+    # link to titles using :ref:`Title text`
+    # https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.graphviz",
+    # link to other Python projects
+    # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
     "sphinx.ext.intersphinx",
-    "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
-    "sphinx_inline_tabs",
-    "sphinx_togglebutton",
-    # "myst_parser",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+# also link to titles using :ref:`path/to/document:Title text`
+# (note that path should not have a leading slash)
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document
+autosectionlabel_prefix_document = True
 
-# List of patterns, relative to source directory, that match files and
+# source files are in this language
+language = "zh_CN"
+# translation files are in this directory
+locale_dirs = ["./locales/"]
+# this should be false so 1 doc file corresponds to 1 translation file
+gettext_compact = False
+gettext_uuid = False
+# allow source texts to keep using outdated translations if they are only marginally changed
+# otherwise any change to source text will cause their translations to not appear
+gettext_allow_fuzzy_translations = True
+
+# list of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_favicon = "_static/favicon.ico"
-
-html_css_files = [
-    "css/custom.css",
+exclude_patterns = [
+    "CONTRIBUTING.md",  # prevent CONTRIBUTING.md from being included in output, optional
+    ".venv",
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
 ]
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "pydata_sphinx_theme"
-
-html_context = {"default_mode": "light"}
-
-html_sidebars = {"index": [], "**": ["search-field", "sidebar-nav-bs"]}
-
-html_theme_options = {
-    "logo": {
-        "text": "Interconnection",
-    },
-    "pygment_light_style": "tango",
-    "pygment_dark_style": "native",
-    "icon_links": [
-        {
-            "name": "GitHub",
-            "url": "https://github.com/secretflow/interconnection",
-            "icon": "fa-brands fa-github",
-            "type": "fontawesome",
-        },
-    ],
-    "secondary_sidebar_items": ["page-toc"],
-}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+autoclass_content = "both"

docs/requirements.txt

@@ -1,6 +1,3 @@
-sphinx==5.3.0
-sphinx-intl
-sphinx-copybutton
-sphinx-togglebutton
-sphinx-inline-tabs
-pydata-sphinx-theme  # theme
+secretflow-doctools~=0.8.5
+sphinx-intl~=2.3
+sphinx~=8.0