Tools: Deprecate calling setuptools directly

[Ryanf55]

This is a draft to support fixing #24862. It doesn't work. I'll let the ROS maintainers know.
https://discourse.ros.org/t/call-for-testing-standards-based-python-packaging-with-colcon/32008

[srmainwaring]

@khancyr - I think this is in draft as Ryan mentions there are still some issues with the upstream colcon-python-project package. Further it looks like we need to do some work on our package structure to prevent the non-ROS parts of ArduPilot from being analysed - see below.

Running on macOS:

Clone and install the colcon extension:

cd ~/ros2_ws/src && git clone https://github.com/colcon/colcon-python-project.git -b devel

cd ~/ros2_ws && colcon build --symlink-install --cmake-args -DBUILD_TESTING=ON -DBUILD_UNIT_TESTS=OFF -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_CXX_STANDARD=17 -DCMAKE_MACOSX_RPATH=FALSE -DUAGENT_SOCKETCAN_PROFILE=OFF -DUAGENT_LOGGER_PROFILE=ON -DUAGENT_USE_SYSTEM_LOGGER=OFF -DUAGENT_USE_SYSTEM_FASTDDS=ON -DUAGENT_USE_SYSTEM_FASTCDR=ON --packages-select colcon-python-project
[1.446s] WARNING:colcon.colcon_python_project.package_identification.pep517:An error occurred while reading metadata for src/ardupilot: error: Multiple top-level packages discovered in a flat-layout: ['Blimp', 'Tools', 'Rover', 'ArduSub', 'modules', 'ArduPlane', 'libraries', 'ArduCopter', 'AntennaTracker'].

To avoid accidental inclusion of unwanted files or directories,
setuptools will not proceed with this build.

If you are trying to create a single distribution with multiple packages
on purpose, you should not rely on automatic discovery.
Instead, consider the following options:

1. set up custom discovery (`find` directive with `include` or `exclude`)
2. use a `src-layout`
3. explicitly set `py_modules` or `packages` with a list of names

To find more information, look for "package discovery" on setuptools docs.
Starting >>> colcon-python-project
--- stderr: colcon-python-project                   
Editable install will be performed using a meta path finder.

Options like `package-data`, `include/exclude-package-data` or
`packages.find.exclude/include` may have no effect.

---
Finished <<< colcon-python-project [0.91s]

Summary: 1 package finished [3.51s]
  1 package had stderr output: colcon-python-project