All imported resource files are placed under the _generated directory to avoid mixing with local changes during commits.

Author: bachelor-dou

.gitignore

@@ -2,4 +2,5 @@ _build/*
 .venv
 .vscode
 .DS_Store
-sources/pytorch/api_doc.rst
+sources/pytorch/api_doc.rst
+sources/_generated

Makefile

@@ -12,8 +12,11 @@ BUILDDIR      = _build
 PROJECT_CONFIGS = \
     _repos/verl/docs/ascend_tutorial:sources/verl \
     _repos/VeOmni/docs:sources/VeOmni \
-	_repos/LLaMA-Factory/docs:sources/LLaMA-Factory \
-	_repos/ms-swift/docs:sources/ms-swift
+    _repos/LLaMA-Factory/docs:sources/LLaMA-Factory \
+    _repos/ms-swift/docs:sources/ms-swift
+
+# Configure all subprojects generated path
+GENERATED_DOCS := sources/_generated
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -25,19 +28,31 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@echo "Initializing submodules..."
-	@git submodule update --init
-	
+	@git submodule update --init --remote
+
+	@echo "Preparing generated docs directory..."
+	@mkdir -p $(GENERATED_DOCS)
+
 	@echo "Copying project documentation..."
 	@for config in $(PROJECT_CONFIGS); do \
 		src=$$(echo $$config | cut -d: -f1); \
-		dst=$$(echo $$config | cut -d: -f2); \
-		# Removing existing index files to avoid conflicts \
+		rel_dst=$$(echo $$config | cut -d: -f2); \
+		dst="$(GENERATED_DOCS)/$$rel_dst"; \
+		echo "Copying $$src -> $$dst"; \
+		\
+		# Clean destination to avoid stale files \
+		rm -rf $$dst; \
+		mkdir -p $$dst; \
+		\
+		# Remove index files from source to avoid conflicts \
 		find $$src -name 'index.*' -delete 2>/dev/null || true; \
+		\
 		echo "Copying $$src to $$dst"; \
-		cp -r $$src/* $$dst/ 2>/dev/null || echo "  Source directory does not exist or is empty: $$src"; \
+		cp -r "$$src"/* "$$dst"/ 2>/dev/null || \
+			echo "  [WARN] Source directory does not exist or is empty: $$src"; \
 	done
-	
+
 	@echo "Cleaning up submodules..."
 	@git submodule deinit -f _repos/*
-	
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sources/LLaMA-Factory/index.rst

@@ -4,6 +4,6 @@ LLaMA-Factory
 .. toctree::
    :maxdepth: 3
 
-   source/advanced/npu_installation.rst
-   source/advanced/npu_training.rst
-   source/advanced/distributed.rst
+   ../_generated/sources/LLaMA-Factory/source/advanced/npu_installation
+   ../_generated/sources/LLaMA-Factory/source/advanced/npu_training
+   ../_generated/sources/LLaMA-Factory/source/advanced/distributed

sources/VeOmni/index.rst

@@ -4,5 +4,5 @@ VeOmni
 .. toctree::
    :maxdepth: 3
 
-   get_started/installation/install_ascend.md
-   hardware_support/get_started_npu.md
+   ../_generated/sources/VeOmni/get_started/installation/install_ascend
+   ../_generated/sources/VeOmni/hardware_support/get_started_npu

sources/ms-swift/index.rst

@@ -4,5 +4,5 @@ ms-swift
 .. toctree::
    :maxdepth: 3
 
-   source/BestPractices/NPU-support.md
-   source_en/BestPractices/NPU-support.md
+   ../_generated/sources/ms-swift/source/BestPractices/NPU-support
+   ../_generated/sources/ms-swift/source_en/BestPractices/NPU-support

sources/roll/index.rst

@@ -1,4 +1,4 @@
-roll
+ROLL
 ============
 
 .. toctree::

sources/verl/index.rst

@@ -4,9 +4,9 @@ verl
 .. toctree::
    :maxdepth: 3
 
-   ascend_quick_start.rst
-   ascend_sglang_quick_start.rst
-   dockerfile_build_guidance.rst
-   ascend_profiling_en.rst
-   ascend_profiling_zh.rst
-   ascend_consistency.rst
+   ../_generated/sources/verl/ascend_quick_start
+   ../_generated/sources/verl/ascend_sglang_quick_start
+   ../_generated/sources/verl/dockerfile_build_guidance
+   ../_generated/sources/verl/ascend_profiling_en
+   ../_generated/sources/verl/ascend_profiling_zh
+   ../_generated/sources/verl/ascend_consistency