Part of #2689, but wanted a clean page to contemplate how best to adapt the API / Python executables to the modified filesystem structure & installation process for cmake.

1. Some of the logic in bin/mrtrix3.py is tailored for running Python executables that are part of external MRtrix3 projects. Relevant documentation here. There, the logic proceeds something like: 1) If a symbolic link to the main repo bin/mrtrix3.py has been made within the external project, that can be used to find the API. 2) Often external projects are built by constructing a softlink to the build script in the main repo and running that directly; that softlink can therefore be used to find the API. Use of PYTHONPATH is a fallback, but if used would kick in before any of this logic.

   This is being made redundant; indeed it's unclear at this point in time exactly what external projects will look like after the cmake changes.

   Suggestion: Remove all support for external modules within the code. PYTHONPATH will remain a viable solution. At the point at which we address compilation of external C++ binaries we will also address external Python executables.

2. It is intended to be possible for a user to define a symbolic link to the executable, and attempting to run that executable will still find the Python API based on a relative path from the resolved symbolic link.

3. The run module includes logic to ensure that if an MRtrix3 executable is invoked, it is the coinciding version of that executable that is invoked rather than the first that appears in PATH, and also there are certain command-line options that may be added to run.command() invocations based on the availability of "standard" MRtrix3 command-line options.

   The logic behind this may need to be revised. Currently, it just looks at the contents of ../../bin/. So if the software is installed into a location that is shared with other software, eg. /usr/local/, that logic will catch a large set of non-MRtrix3 commands.

   Suggestion: The build stage of cmake could collect a list of MRtrix3 executables, and write it to a text file within lib/mrtrix3/ in the build directory. lib/mrtrix3/__init__.py would then read from this file.

4. It was hypothesized that it would be nice to be able to:

   1. Run MRtrix3 Python scripts from either an installed location or the build directory, and for point 3 above to still be satisfied.

   2. Modify the contents of Python executables within the source directory, and have those changes reflected in the build directory without having to re-run the build step of cmake.

      However on reflection it may be tricky to support both this feature and point 2 above. It would be treating softlinks in different ways, and also ideally this modify-without-build feature would apply to the API and script algorithms also.

   Suggestions: For point i., as long as the directory structure is consistent between build and install, and there isn't any softlink trickery, it should work out of the box. For point ii., just rely on cmake build to copy any Python updates made in the source code into the build directory.

5. Already mentioned in Change build system to CMake #2689, but relevant here also: Placement of the script algorithms.

   Before the cmake changes, there are executable Python scripts in bin/, APIs in lib/mrtrix3/, and algorithm source code in lib/mrtrix3/<exename>/*.py. Thus far for cmake this has all just been moved into new directory python/* but the relative structure is unchanged.

   Suggestions: There's multiple options here. One I'm increasingly liking as suggested by @aaroncapon is to move the sub-directories of python/lib/mrtrix3/ (ie. the script algorithms) into python/src/mrtrix3/, and within the build / installation directory populate src/mrtrix3/ with these contents. @daljit46 do you see any issue with the build / installation containing a src/mrtrix3/ directory?