Merge branch 'feature/py23_docs' into 'master'

docs: Make the Python scripts Python 2&3 compatible

See merge request idf/esp-idf!3226

docs/conf_common.py

@@ -14,6 +14,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+from __future__ import print_function
+from __future__ import unicode_literals
 import sys, os
 import re
 import subprocess

docs/gen-dxd.py

@@ -8,6 +8,10 @@
 # CONDITIONS OF ANY KIND, either express or implied.
 #
 
+from __future__ import print_function
+from __future__ import unicode_literals
+from builtins import range
+from io import open
 import sys
 import os
 import re
@@ -50,12 +54,12 @@ def get_doxyfile_input():
 
     """
     if not os.path.isfile(doxyfile_path):
-        print "Doxyfile '%s' does not exist!" % doxyfile_path
+        print("Doxyfile '%s' does not exist!" % doxyfile_path)
         sys.exit()
 
-    print "Getting Doxyfile's INPUT"
+    print("Getting Doxyfile's INPUT")
 
-    input_file = open(doxyfile_path, "r")
+    input_file = open(doxyfile_path, "r", encoding='utf-8')
 
     line = input_file.readline()
     # read contents of Doxyfile until 'INPUT' statement
@@ -258,14 +262,14 @@ def generate_api_inc_files():
     """
 
     if not os.path.isdir(xml_directory_path):
-        print "Directory %s does not exist!" % xml_directory_path
+        print("Directory %s does not exist!" % xml_directory_path)
         sys.exit()
 
     if not os.path.exists(inc_directory_path):
         os.makedirs(inc_directory_path)
 
     list_to_generate = get_doxyfile_input()
-    print "Generating 'api_name.inc' files with Doxygen directives"
+    print("Generating 'api_name.inc' files with Doxygen directives")
     for header_file_path in list_to_generate.splitlines():
         api_name = get_api_name(header_file_path)
         inc_file_path = inc_directory_path + "/" + api_name + ".inc"
@@ -273,11 +277,11 @@ def generate_api_inc_files():
 
         previous_rst_output = ''
         if os.path.isfile(inc_file_path):
-            with open(inc_file_path, "r") as inc_file_old:
+            with open(inc_file_path, "r", encoding='utf-8') as inc_file_old:
                 previous_rst_output = inc_file_old.read()
 
         if previous_rst_output != rst_output:
-            with open(inc_file_path, "w") as inc_file:
+            with open(inc_file_path, "w", encoding='utf-8') as inc_file:
                 inc_file.write(rst_output)
 
 
@@ -290,23 +294,23 @@ if __name__ == "__main__":
     # Process command line arguments, if any
     if len(sys.argv) > 1:
         if not os.path.isdir(xml_directory_path):
-            print "Directory %s does not exist!" % xml_directory_path
+            print("Directory %s does not exist!" % xml_directory_path)
             sys.exit()
         header_file_path = sys.argv[1]
         api_name = get_api_name(header_file_path)
         if api_name:
             rst_output = generate_directives(header_file_path)
-            print "Doxygen directives for '%s'" % header_file_path
-            print
-            print rst_output
+            print("Doxygen directives for '%s'" % header_file_path)
+            print()
+            print(rst_output)
         else:
-            print "Options to execute 'gen-dxd.py' application:"
-            print "1: $ python gen-dxd.py"
-            print "   Generate API 'header_file.inc' files for headers defined in '%s'" % doxyfile_path
-            print "2: $ python gen-dxd.py header_file_path"
-            print "   Print out Doxygen directives for a single header file"
-            print "   example: $ python gen-dxd.py mdns/include/mdns.h"
-            print "   NOTE: Run Doxygen first to get XML files for the header file"
+            print("Options to execute 'gen-dxd.py' application:")
+            print("1: $ python gen-dxd.py")
+            print("   Generate API 'header_file.inc' files for headers defined in '%s'" % doxyfile_path)
+            print("2: $ python gen-dxd.py header_file_path")
+            print("   Print out Doxygen directives for a single header file")
+            print("   example: $ python gen-dxd.py mdns/include/mdns.h")
+            print("   NOTE: Run Doxygen first to get XML files for the header file")
 
         sys.exit()
 

docs/gen-version-specific-includes.py

@@ -4,6 +4,9 @@
 # Python script to generate ReSTructured Text .inc snippets
 # with version-based content for this IDF version
 
+from __future__ import print_function
+from __future__ import unicode_literals
+from io import open
 import subprocess
 import os
 import sys
@@ -129,7 +132,7 @@ def write_git_clone_inc(template, out_dir, version, ver_type, is_stable):
             "zipfile_note" : zipfile["stable"] if is_stable else zipfile["unstable"]
         }
     out_file = os.path.join(out_dir, "git-clone.inc")
-    with open(out_file, "w") as f:
+    with open(out_file, "w", encoding='utf-8') as f:
         f.write(template["template"] % args)
     print("%s written" % out_file)
 
@@ -142,7 +145,7 @@ def write_version_note(template, out_dir, version, ver_type, is_stable):
     else:
         content = template["branch"] % (ver_type, version)
     out_file = os.path.join(out_dir, "version-note.inc")
-    with open(out_file, "w") as f:
+    with open(out_file, "w", encoding='utf-8') as f:
         f.write(content)
     print("%s written" % out_file)
 

docs/link-roles.py

@@ -1,5 +1,7 @@
 # based on http://protips.readthedocs.io/link-roles.html
 
+from __future__ import print_function
+from __future__ import unicode_literals
 import re
 import os
 from docutils import nodes
@@ -8,9 +10,9 @@ from local_util import run_cmd_get_output
 def get_github_rev():
     path = run_cmd_get_output('git rev-parse --short HEAD')
     tag = run_cmd_get_output('git describe --exact-match')
-    print ('Git commit ID: ', path)
+    print('Git commit ID: ', path)
     if len(tag):
-        print ('Git tag: ', tag)
+        print('Git tag: ', tag)
         path = tag
     return path
 

docs/local_util.py

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import unicode_literals
+from io import open
 import re
 import os
 import shutil
@@ -25,10 +27,10 @@ def files_equal(path_1, path_2):
     if not os.path.exists(path_1) or not os.path.exists(path_2):
         return False
     file_1_contents = ''
-    with open(path_1, "r") as f_1:
+    with open(path_1, "r", encoding='utf-8') as f_1:
         file_1_contents = f_1.read()
     file_2_contents = ''
-    with open(path_2, "r") as f_2:
+    with open(path_2, "r", encoding='utf-8') as f_2:
         file_2_contents = f_2.read()
     return file_1_contents == file_2_contents