From 1e2c7002f7a5dd04989d83b9967b88251a350c8e Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Tue, 28 Apr 2026 18:55:51 +0800 Subject: [PATCH] Consolidate docs into one Sphinx project with language subdirectories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt WebRunner's docs layout: a single Sphinx project under docs/source/ with per-language subdirectories (Eng/, Zh-TW/, Zh-CN/) and a language-neutral API/ tree. The top-level index.rst is a slim hero with four toctrees pointing at chapter sub-indexes (eng_index, zh_tw_index, zh_cn_index, api_index); each sub-index has chapter sections that toctree to the chapter docs. Cross-language navigation now works through normal Sphinx toctrees inside the same build — relative ../html-zh-TW/ links and per- language RTD projects are no longer needed. Drop the per-language .readthedocs.zh-*.yaml files, drop the source.zh-TW/ and source.zh-CN/ source trees, drop the per-language conf.py + index, and simplify make.bat / Makefile to a single html target. Single API tree built once from English autodoc avoids the duplicate object descriptions warnings the three-tree layout produced. --- .readthedocs.yaml | 12 +- .readthedocs.zh-CN.yaml | 22 -- .readthedocs.zh-TW.yaml | 22 -- docs/Makefile | 10 +- docs/make.bat | 18 -- docs/source.zh-CN/api/local.rst | 47 ---- docs/source.zh-CN/api/notify.rst | 8 - docs/source.zh-CN/api/progress.rst | 11 - docs/source.zh-CN/api/project.rst | 8 - docs/source.zh-CN/api/remote.rst | 173 ------------- docs/source.zh-CN/api/scheduler.rst | 16 -- docs/source.zh-CN/api/server.rst | 28 -- docs/source.zh-CN/api/trigger.rst | 12 - docs/source.zh-CN/api/ui.rst | 81 ------ docs/source.zh-CN/api/utils.rst | 11 - docs/source.zh-CN/conf.py | 61 ----- docs/source.zh-CN/index.rst | 221 ---------------- docs/source.zh-TW/api/client.rst | 5 - docs/source.zh-TW/api/core.rst | 86 ------ docs/source.zh-TW/api/local.rst | 47 ---- docs/source.zh-TW/api/notify.rst | 8 - docs/source.zh-TW/api/progress.rst | 11 - docs/source.zh-TW/api/project.rst | 8 - docs/source.zh-TW/api/remote.rst | 173 ------------- docs/source.zh-TW/api/scheduler.rst | 16 -- docs/source.zh-TW/api/server.rst | 28 -- docs/source.zh-TW/api/trigger.rst | 12 - docs/source.zh-TW/api/ui.rst | 81 ------ docs/source.zh-TW/api/utils.rst | 11 - docs/source.zh-TW/conf.py | 61 ----- docs/source.zh-TW/index.rst | 221 ---------------- docs/source/API/api_index.rst | 174 +++++++++++++ .../api => source/API}/client.rst | 0 .../{source.zh-CN/api => source/API}/core.rst | 0 docs/source/{api => API}/local.rst | 0 docs/source/{api => API}/notify.rst | 0 docs/source/{api => API}/progress.rst | 0 docs/source/{api => API}/project.rst | 0 docs/source/{api => API}/remote.rst | 0 docs/source/{api => API}/scheduler.rst | 0 docs/source/{api => API}/server.rst | 0 docs/source/{api => API}/trigger.rst | 0 docs/source/{api => API}/ui.rst | 0 docs/source/{api => API}/utils.rst | 0 docs/source/{ => Eng}/architecture.rst | 0 docs/source/Eng/eng_index.rst | 244 ++++++++++++++++++ docs/source/{ => Eng}/usage/cli.rst | 0 docs/source/{ => Eng}/usage/cloud.rst | 0 docs/source/{ => Eng}/usage/config.rst | 0 docs/source/{ => Eng}/usage/dag.rst | 0 docs/source/{ => Eng}/usage/events.rst | 0 docs/source/{ => Eng}/usage/gui.rst | 0 docs/source/{ => Eng}/usage/local.rst | 0 docs/source/{ => Eng}/usage/mcp.rst | 0 docs/source/{ => Eng}/usage/notifications.rst | 0 docs/source/{ => Eng}/usage/plugins.rst | 0 docs/source/{ => Eng}/usage/quickstart.rst | 0 docs/source/{ => Eng}/usage/reliability.rst | 0 docs/source/{ => Eng}/usage/servers.rst | 0 docs/source/{ => Eng}/usage/transfer.rst | 0 .../Zh-CN}/architecture.rst | 0 .../Zh-CN}/usage/cli.rst | 0 .../Zh-CN}/usage/cloud.rst | 0 .../Zh-CN}/usage/config.rst | 0 .../Zh-CN}/usage/dag.rst | 0 .../Zh-CN}/usage/events.rst | 0 .../Zh-CN}/usage/gui.rst | 0 .../Zh-CN}/usage/local.rst | 0 .../Zh-CN}/usage/mcp.rst | 0 .../Zh-CN}/usage/notifications.rst | 0 .../Zh-CN}/usage/plugins.rst | 0 .../Zh-CN}/usage/quickstart.rst | 0 .../Zh-CN}/usage/reliability.rst | 0 .../Zh-CN}/usage/servers.rst | 0 .../Zh-CN}/usage/transfer.rst | 0 docs/source/Zh-CN/zh_cn_index.rst | 239 +++++++++++++++++ .../Zh-TW}/architecture.rst | 0 .../Zh-TW}/usage/cli.rst | 0 .../Zh-TW}/usage/cloud.rst | 0 .../Zh-TW}/usage/config.rst | 0 .../Zh-TW}/usage/dag.rst | 0 .../Zh-TW}/usage/events.rst | 0 .../Zh-TW}/usage/gui.rst | 0 .../Zh-TW}/usage/local.rst | 0 .../Zh-TW}/usage/mcp.rst | 0 .../Zh-TW}/usage/notifications.rst | 0 .../Zh-TW}/usage/plugins.rst | 0 .../Zh-TW}/usage/quickstart.rst | 0 .../Zh-TW}/usage/reliability.rst | 0 .../Zh-TW}/usage/servers.rst | 0 .../Zh-TW}/usage/transfer.rst | 0 docs/source/Zh-TW/zh_tw_index.rst | 239 +++++++++++++++++ docs/source/api/client.rst | 5 - docs/source/api/core.rst | 86 ------ docs/source/conf.py | 6 - docs/source/index.rst | 221 ++-------------- 96 files changed, 930 insertions(+), 1813 deletions(-) delete mode 100644 .readthedocs.zh-CN.yaml delete mode 100644 .readthedocs.zh-TW.yaml delete mode 100644 docs/source.zh-CN/api/local.rst delete mode 100644 docs/source.zh-CN/api/notify.rst delete mode 100644 docs/source.zh-CN/api/progress.rst delete mode 100644 docs/source.zh-CN/api/project.rst delete mode 100644 docs/source.zh-CN/api/remote.rst delete mode 100644 docs/source.zh-CN/api/scheduler.rst delete mode 100644 docs/source.zh-CN/api/server.rst delete mode 100644 docs/source.zh-CN/api/trigger.rst delete mode 100644 docs/source.zh-CN/api/ui.rst delete mode 100644 docs/source.zh-CN/api/utils.rst delete mode 100644 docs/source.zh-CN/conf.py delete mode 100644 docs/source.zh-CN/index.rst delete mode 100644 docs/source.zh-TW/api/client.rst delete mode 100644 docs/source.zh-TW/api/core.rst delete mode 100644 docs/source.zh-TW/api/local.rst delete mode 100644 docs/source.zh-TW/api/notify.rst delete mode 100644 docs/source.zh-TW/api/progress.rst delete mode 100644 docs/source.zh-TW/api/project.rst delete mode 100644 docs/source.zh-TW/api/remote.rst delete mode 100644 docs/source.zh-TW/api/scheduler.rst delete mode 100644 docs/source.zh-TW/api/server.rst delete mode 100644 docs/source.zh-TW/api/trigger.rst delete mode 100644 docs/source.zh-TW/api/ui.rst delete mode 100644 docs/source.zh-TW/api/utils.rst delete mode 100644 docs/source.zh-TW/conf.py delete mode 100644 docs/source.zh-TW/index.rst create mode 100644 docs/source/API/api_index.rst rename docs/{source.zh-CN/api => source/API}/client.rst (100%) rename docs/{source.zh-CN/api => source/API}/core.rst (100%) rename docs/source/{api => API}/local.rst (100%) rename docs/source/{api => API}/notify.rst (100%) rename docs/source/{api => API}/progress.rst (100%) rename docs/source/{api => API}/project.rst (100%) rename docs/source/{api => API}/remote.rst (100%) rename docs/source/{api => API}/scheduler.rst (100%) rename docs/source/{api => API}/server.rst (100%) rename docs/source/{api => API}/trigger.rst (100%) rename docs/source/{api => API}/ui.rst (100%) rename docs/source/{api => API}/utils.rst (100%) rename docs/source/{ => Eng}/architecture.rst (100%) create mode 100644 docs/source/Eng/eng_index.rst rename docs/source/{ => Eng}/usage/cli.rst (100%) rename docs/source/{ => Eng}/usage/cloud.rst (100%) rename docs/source/{ => Eng}/usage/config.rst (100%) rename docs/source/{ => Eng}/usage/dag.rst (100%) rename docs/source/{ => Eng}/usage/events.rst (100%) rename docs/source/{ => Eng}/usage/gui.rst (100%) rename docs/source/{ => Eng}/usage/local.rst (100%) rename docs/source/{ => Eng}/usage/mcp.rst (100%) rename docs/source/{ => Eng}/usage/notifications.rst (100%) rename docs/source/{ => Eng}/usage/plugins.rst (100%) rename docs/source/{ => Eng}/usage/quickstart.rst (100%) rename docs/source/{ => Eng}/usage/reliability.rst (100%) rename docs/source/{ => Eng}/usage/servers.rst (100%) rename docs/source/{ => Eng}/usage/transfer.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/architecture.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/cli.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/cloud.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/config.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/dag.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/events.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/gui.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/local.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/mcp.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/notifications.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/plugins.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/quickstart.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/reliability.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/servers.rst (100%) rename docs/{source.zh-CN => source/Zh-CN}/usage/transfer.rst (100%) create mode 100644 docs/source/Zh-CN/zh_cn_index.rst rename docs/{source.zh-TW => source/Zh-TW}/architecture.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/cli.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/cloud.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/config.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/dag.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/events.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/gui.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/local.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/mcp.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/notifications.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/plugins.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/quickstart.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/reliability.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/servers.rst (100%) rename docs/{source.zh-TW => source/Zh-TW}/usage/transfer.rst (100%) create mode 100644 docs/source/Zh-TW/zh_tw_index.rst delete mode 100644 docs/source/api/client.rst delete mode 100644 docs/source/api/core.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f5ddeac..496e3ff 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,11 +1,9 @@ # .readthedocs.yaml -# Read the Docs configuration file for the English ("fileautomation") project. -# Sibling files .readthedocs.zh-TW.yaml and .readthedocs.zh-CN.yaml configure -# the two translation projects. Wire each translation project to its own YAML -# in the RTD project admin (Settings → Default settings → Path), and link the -# three projects via the main project's Translations tab. +# Read the Docs configuration file. The single Sphinx project under +# docs/source/ builds all three languages into one site (subdirectories +# Eng/, Zh-TW/, Zh-CN/, and API/) — cross-language navigation works through +# normal Sphinx toctrees, with no per-language project required. # See https://docs.readthedocs.io/en/stable/config-file/v2.html -# https://docs.readthedocs.io/en/stable/localization.html # Required version: 2 @@ -16,7 +14,7 @@ build: tools: python: "3.11" -# Build the English documentation in docs/source with Sphinx. +# Build the documentation in docs/source/ with Sphinx. sphinx: configuration: docs/source/conf.py diff --git a/.readthedocs.zh-CN.yaml b/.readthedocs.zh-CN.yaml deleted file mode 100644 index 453ae18..0000000 --- a/.readthedocs.zh-CN.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# .readthedocs.zh-CN.yaml -# Read the Docs configuration file for the Simplified Chinese -# ("fileautomation-zh-cn") translation project. Linked from the main -# "fileautomation" project's Translations tab so RTD serves it at -# https://fileautomation.readthedocs.io/zh_CN//. -# See https://docs.readthedocs.io/en/stable/config-file/v2.html -# https://docs.readthedocs.io/en/stable/localization.html - -version: 2 - -build: - os: ubuntu-22.04 - tools: - python: "3.11" - -# Build the Simplified Chinese documentation in docs/source.zh-CN with Sphinx. -sphinx: - configuration: docs/source.zh-CN/conf.py - -python: - install: - - requirements: docs/requirements.txt diff --git a/.readthedocs.zh-TW.yaml b/.readthedocs.zh-TW.yaml deleted file mode 100644 index 3b8e46b..0000000 --- a/.readthedocs.zh-TW.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# .readthedocs.zh-TW.yaml -# Read the Docs configuration file for the Traditional Chinese -# ("fileautomation-zh-tw") translation project. Linked from the main -# "fileautomation" project's Translations tab so RTD serves it at -# https://fileautomation.readthedocs.io/zh_TW//. -# See https://docs.readthedocs.io/en/stable/config-file/v2.html -# https://docs.readthedocs.io/en/stable/localization.html - -version: 2 - -build: - os: ubuntu-22.04 - tools: - python: "3.11" - -# Build the Traditional Chinese documentation in docs/source.zh-TW with Sphinx. -sphinx: - configuration: docs/source.zh-TW/conf.py - -python: - install: - - requirements: docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile index b304cc6..01e66b5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,7 +4,7 @@ SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = _build -.PHONY: help html clean html-zh-TW html-zh-CN html-all +.PHONY: help html clean help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) @@ -12,13 +12,5 @@ help: html: @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -html-zh-TW: - @$(SPHINXBUILD) -b html source.zh-TW "$(BUILDDIR)/html-zh-TW" $(SPHINXOPTS) - -html-zh-CN: - @$(SPHINXBUILD) -b html source.zh-CN "$(BUILDDIR)/html-zh-CN" $(SPHINXOPTS) - -html-all: html html-zh-TW html-zh-CN - clean: @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) diff --git a/docs/make.bat b/docs/make.bat index cf6d346..45d7073 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -18,27 +18,9 @@ if errorlevel 9009 ( exit /b 1 ) -if "%1" == "html-zh-TW" goto build-zh-TW -if "%1" == "html-zh-CN" goto build-zh-CN -if "%1" == "html-all" goto build-all - %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end -:build-zh-TW -%SPHINXBUILD% -b html source.zh-TW %BUILDDIR%\html-zh-TW %SPHINXOPTS% %O% -goto end - -:build-zh-CN -%SPHINXBUILD% -b html source.zh-CN %BUILDDIR%\html-zh-CN %SPHINXOPTS% %O% -goto end - -:build-all -%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -%SPHINXBUILD% -b html source.zh-TW %BUILDDIR%\html-zh-TW %SPHINXOPTS% %O% -%SPHINXBUILD% -b html source.zh-CN %BUILDDIR%\html-zh-CN %SPHINXOPTS% %O% -goto end - :help %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% diff --git a/docs/source.zh-CN/api/local.rst b/docs/source.zh-CN/api/local.rst deleted file mode 100644 index 9dbf0a2..0000000 --- a/docs/source.zh-CN/api/local.rst +++ /dev/null @@ -1,47 +0,0 @@ -本地操作 -======== - -.. automodule:: automation_file.local.file_ops - :members: - -.. automodule:: automation_file.local.dir_ops - :members: - -.. automodule:: automation_file.local.zip_ops - :members: - -.. automodule:: automation_file.local.sync_ops - :members: - -.. automodule:: automation_file.local.safe_paths - :members: - -.. automodule:: automation_file.local.shell_ops - :members: - -.. automodule:: automation_file.local.tar_ops - :members: - -.. automodule:: automation_file.local.json_edit - :members: - -.. automodule:: automation_file.local.conditional - :members: - -.. automodule:: automation_file.local.archive_ops - :members: - -.. automodule:: automation_file.local.diff_ops - :members: - -.. automodule:: automation_file.local.mime - :members: - -.. automodule:: automation_file.local.templates - :members: - -.. automodule:: automation_file.local.trash - :members: - -.. automodule:: automation_file.local.versioning - :members: diff --git a/docs/source.zh-CN/api/notify.rst b/docs/source.zh-CN/api/notify.rst deleted file mode 100644 index 15b4aa1..0000000 --- a/docs/source.zh-CN/api/notify.rst +++ /dev/null @@ -1,8 +0,0 @@ -通知 -==== - -.. automodule:: automation_file.notify.sinks - :members: - -.. automodule:: automation_file.notify.manager - :members: diff --git a/docs/source.zh-CN/api/progress.rst b/docs/source.zh-CN/api/progress.rst deleted file mode 100644 index e7a9306..0000000 --- a/docs/source.zh-CN/api/progress.rst +++ /dev/null @@ -1,11 +0,0 @@ -进度与取消 -========== - -传输的可选仪表化。对 :func:`~automation_file.download_file`、 -:func:`s3_upload_file` 或 :func:`s3_download_file` 传入 -``progress_name="