Improve check for system tests TOC in providers (#28666)

The TOC for system tests check did not check if the index has been
added before automatically generated part of the index.

This PR checks if the index is added before the automatically generated
lines and explains that the entry should be added before the comment
indicating beginning of the automatucally generated part.

docs/apache-airflow-providers-ftp/index.rst

@@ -43,21 +43,20 @@ Content
     PyPI Repository <https://pypi.org/project/apache-airflow-providers-ftp/>
     Installing from sources <installing-providers-from-sources>
 
-.. THE REMAINDER OF THE FILE IS AUTOMATICALLY GENERATED. IT WILL BE OVERWRITTEN AT RELEASE TIME!
+.. toctree::
+    :hidden:
+    :caption: System tests
 
+    System Tests <_api/tests/system/providers/ftp/index>
+
+.. THE REMAINDER OF THE FILE IS AUTOMATICALLY GENERATED. IT WILL BE OVERWRITTEN AT RELEASE TIME!
 
 .. toctree::
     :maxdepth: 1
     :caption: Commits
 
     Detailed list of commits <commits>
 
-.. toctree::
-    :hidden:
-    :caption: System tests
-
-    System Tests <_api/tests/system/providers/ftp/index>
-
 Package apache-airflow-providers-ftp
 ------------------------------------------------------
 

scripts/ci/pre_commit/pre_commit_check_system_tests_hidden_in_index.py

@@ -56,10 +56,16 @@ def check_system_test_entry_hidden(provider_index: Path):
 """
     index_text = provider_index.read_text()
     system_tests_path = AIRFLOW_SOURCES_ROOT / "tests" / "system" / "providers" / provider_path
+    index_text_manual = index_text.split(
+        ".. THE REMAINDER OF THE FILE IS AUTOMATICALLY GENERATED. IT WILL BE OVERWRITTEN AT RELEASE TIME!"
+    )[0]
     if system_tests_path.exists():
-        if expected_text not in index_text:
+        if expected_text not in index_text_manual:
             console.print(f"[red]The {provider_index} does not contain System Tests TOC.\n")
-            console.print(f"[yellow]Make sure to add those lines to {provider_index}:\n")
+            console.print(
+                f"[yellow]Make sure to add those lines to {provider_index} BEFORE (!) the line "
+                f"starting with  '.. THE REMINDER OF THE FILE':\n"
+            )
             console.print(expected_text, markup=False)
             errors.append(provider_index)
         else: