diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..d9f573e --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,145 @@ +# 文档贡献指南 | Contributing docs + +- [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 +``` + +用浏览器访问 （或其它端口号），你应当能看到类似下图的页面，其中 +将会列出在本地构建好的文档版本： + +
+ the sitemap page +
+ +点击一个版本即可打开对应预览，你应当能看到类似下图的页面： + +
+ the content page +
+ +> [!TIP] +> +> 你可以保持预览服务器一直开启：在重新构建文档后，刷新页面即可看到更新的内容。 + +## 文件清理 + +以上流程会产生额外的临时文件，这些文件全部位于 [\_build](./_build/) 目录下。如果需要清理 +，可以执行： + +```sh +secretflow-doctools clean +``` + +## 报告问题 + +如果在以上过程中遇到报错、预览无法显示等问题，可以提交问题到 +。 + +文档内容及本项目代码的相关问题请提交到本项目的 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/ diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..1cbbac8 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/_static/CONTRIBUTING/preview-content.png b/docs/_static/CONTRIBUTING/preview-content.png new file mode 100644 index 0000000..690a654 Binary files /dev/null and b/docs/_static/CONTRIBUTING/preview-content.png differ diff --git a/docs/_static/CONTRIBUTING/preview-sitemap.png b/docs/_static/CONTRIBUTING/preview-sitemap.png new file mode 100644 index 0000000..93aef68 Binary files /dev/null and b/docs/_static/CONTRIBUTING/preview-sitemap.png differ diff --git a/docs/conf.py b/docs/conf.py index 4c6b4d1..25e6c2b 100644 --- a/docs/conf.py +++ b/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" diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 954237b..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/requirements.txt b/docs/requirements.txt index 72f0a97..57915fa 100644 --- a/docs/requirements.txt +++ b/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