BLD: Change cyg2win32 to use the cygpath utility.

The old function only handled the default `/cygdrive` prefix.  This
can be customized to different values: `/` and `/mnt` are both common.
`/proc/cygdrive` does the same thing, regardless of user customization.

`cygpath` handles all of these.  There's also a C function if you'd
prefer to avoid the `fork()` call, which tends to be slow on Cygwin.

Edit: Fix the cyg2win32 function to have correct types.

It returned bytes earlier; this should return a string.

Edit: Fix docsrting to follow numpydoc.

BLD,DOC: Expand documentation for cyg2win32

Fix a misleading statement, and expand on the things `cygpath`
handles that can otherwise be tricky to get right.

Author: DWesl

numpy/distutils/misc_util.py

@@ -376,10 +376,42 @@ def blue_text(s):
 
 #########################
 
-def cyg2win32(path):
-    if sys.platform=='cygwin' and path.startswith('/cygdrive'):
-        path = path[10] + ':' + os.path.normcase(path[11:])
-    return path
+def cyg2win32(path: str) -> str:
+    """Convert a path from Cygwin-native to Windows-native.
+
+    Uses the cygpath utility (part of the Base install) to do the actual
+    conversion.  Falls back to returning the original path if this fails.
+
+    Handles the default ``/cygdrive`` mount prefix as well as the ``/proc/cygdrive``
+    portable prefix, custom cygdrive prefixes such as ``/`` or ``/mnt``, and
+    absolute paths such as ``/usr/src/`` or ``/home/username``
+
+    Parameters
+    ----------
+    path : str
+       The path to convert
+
+    Returns
+    -------
+    converted_path : str
+        The converted path
+
+    Notes
+    -----
+    Documentation for cygpath utility:
+    https://cygwin.com/cygwin-ug-net/cygpath.html
+    Documentation for the C function it wraps:
+    https://cygwin.com/cygwin-api/func-cygwin-conv-path.html
+
+    """
+    if sys.platform != "cygwin":
+        return path
+    try:
+        return subprocess.check_output(
+            ["/usr/bin/cygpath", "--windows", path], universal_newlines=True
+        )
+    except subprocess.CalledProcessError:
+        return path
 
 def mingw32():
     """Return true when using mingw32 environment.