[Clang-Tidy] Update documentation for running Clang-Tidy in parallel and automation scripts

Author: HARSHIL2836R

clang-tools-extra/docs/clang-tidy/index.rst

@@ -41,38 +41,6 @@ parameters file:
 
   $ clang-tidy @parameters_file
 
-Running Clang-Tidy on Multiple Files
-=====================================
-
-For projects with multiple source files, you can use the :program:`run-clang-tidy.py`
-script to run :program:`clang-tidy` over all files in a compilation database in
-parallel. This script is included with clang-tidy and provides a convenient way
-to analyze entire projects efficiently.
-
-The script requires a compilation database (``compile_commands.json``) which can
-be generated by build systems like CMake (using ``-DCMAKE_EXPORT_COMPILE_COMMANDS=ON``)
-or by tools like Bear.
-
-Example invocations:
-
-.. code-block:: console
-
-  # Run clang-tidy on all files in the compilation database
-  $ run-clang-tidy.py
-
-  # Run with specific checks and apply fixes
-  $ run-clang-tidy.py -fix -checks=-*,readability-*
-
-  # Run on specific files/directories with header filtering
-  $ run-clang-tidy.py src/ -header-filter=src/
-
-  # Run with parallel execution (uses all CPU cores by default)
-  $ run-clang-tidy.py -j 4
-
-The script supports most of the same options as :program:`clang-tidy` itself,
-including ``-checks=``, ``-fix``, ``-header-filter=``, and configuration options.
-Run ``run-clang-tidy.py --help`` for a complete list of available options.
-
 :program:`clang-tidy` has its own checks and can also run Clang Static Analyzer
 checks. Each check has a name and the checks to run can be chosen using the
 ``-checks=`` option, which specifies a comma-separated list of positive and
@@ -363,6 +331,47 @@ An overview of all the command-line options:
         some-check.SomeOption: 'some value'
       ...
 
+Clang-Tidy Automation
+=====================
+
+:program:`clang-tidy` can analyze multiple source files by specifying them on the
+command line or by using a compilation database. For larger projects, automation
+scripts provide additional functionality like parallel execution and integration
+with version control systems.
+
+Running Clang-Tidy in Parallel
+-------------------------------
+
+:program:`clang-tidy` can process multiple files sequentially, but for projects
+with many source files, the :program:`run-clang-tidy.py` script provides parallel
+execution to significantly reduce analysis time. This script is included with
+clang-tidy and runs :program:`clang-tidy` over all files in a compilation database
+concurrently.
+
+The script requires a compilation database (``compile_commands.json``) which can
+be generated by build systems like CMake (using ``-DCMAKE_EXPORT_COMPILE_COMMANDS=ON``)
+or by tools like `Bear`_.
+
+The script supports most of the same options as :program:`clang-tidy` itself,
+including ``-checks=``, ``-fix``, ``-header-filter=``, and configuration options.
+Run ``run-clang-tidy.py --help`` for a complete list of available options.
+
+Example invocations:
+
+.. code-block:: console
+
+  # Run clang-tidy on all files in the compilation database in parallel
+  $ run-clang-tidy.py
+
+  # Run with specific checks and apply fixes
+  $ run-clang-tidy.py -fix -checks=-*,readability-*
+
+  # Run on specific files/directories with header filtering
+  $ run-clang-tidy.py -header-filter=src/ src/
+
+  # Run with parallel execution (uses all CPU cores by default)
+  $ run-clang-tidy.py -j 4
+
 .. _clang-tidy-nolint:
 
 Suppressing Undesired Diagnostics
@@ -485,5 +494,6 @@ example, ``NOLINTBEGIN(check-name)`` can be paired with
 :program:`clang-tidy` will generate a ``clang-tidy-nolint`` error diagnostic if
 any ``NOLINTBEGIN``/``NOLINTEND`` comment violates these requirements.
 
+.. _Bear: https://github.com/rizsotto/Bear
 .. _LibTooling: https://clang.llvm.org/docs/LibTooling.html
 .. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html