docs: Do not use shell=True in dart_domain.py (#2405)

This fixes a problem that we accidentally introduced in a recent PR: the
`shell=True` setting requires that the arguments were passed as a single
string instead of a list. Passing as a string, in turn, is somewhat
problematic because the file names need to be escaped, and there is no
utility function to make this escaping cross-platform.

So, instead we'll use the standard `shell=False`, and invoke
`dartdoc_json.bat` on Windows instead of simply `dartdoc_json`. Hope
this would work.

doc/_sphinx/extensions/dart_domain.py

@@ -2,7 +2,6 @@ import json
 import os
 import re
 import subprocess
-import sys
 import tempfile
 from typing import List, Tuple, Dict, Optional, Set, Any
 
@@ -168,14 +167,20 @@ class DartdocDirective(SphinxDirective):
 
     def _scan_source_file(self):
         with tempfile.NamedTemporaryFile(mode='rt', suffix='.json', delete=False) as temp_file:
+            # Note: on Windows, a temporary file cannot be opened in another
+            # process if it is already open in this process. Thus, we need to
+            # close the file handle first before handing the file name to
+            # `subprocess.run()`.
+            temp_file.close()
             try:
-                temp_file.close()
+                executable = 'dartdoc_json'
+                if os.name == 'nt':  # Windows
+                    executable = 'dartdoc_json.bat'
                 subprocess.run(
-                    ['dartdoc_json', self.source_file, '--output', temp_file.name],
+                    [executable, self.source_file, '--output', temp_file.name],
                     stdout=subprocess.PIPE,
                     stderr=subprocess.STDOUT,
                     check=True,
-                    shell=True,
                 )
                 with open(temp_file.name, 'r') as t:
                     json_string = t.read()