doc: Fix doc builds on Windows MINGW32, add some doc build documentation

Using "find" doesn't work properly in MINGW32 Python, even if a MINGW32 find.exe
is on the PATH...

diff --git a/docs/README.md b/docs/README.md
index 6c91573af81b638f606bd3c5afe9a4de1121f413..89a0db0a9e42e1a7917bc43cf34cbcb3a305c17b 100644 (file)
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,3 +14,18 @@ Use actual documentation generated within about 20 minutes on each commit:
 The above URLs are all for the master branch latest version. Click the drop-down in the bottom left to choose a stable version or to download a PDF.
 
 
+# Building Documentation
+
+* Install `make` and `doxygen` for your platform (`make` may already be installed as an ESP-IDF prerequisite).
+* Change to either the docs/en or docs/zh_CN subdirectory and run `make html`
+* `make` will probably prompt you to run a python pip install step to get some other Python-related prerequisites. Run the command as shown, then re-run `make html` to build the docs.
+
+## For MSYS2 MINGW32 on Windows
+
+If using Windows and the MSYS2 MINGW32 terminal, run this command before running "make html" the first time:
+
+```
+pacman -S doxygen mingw-w64-i686-python2-pillow
+```
+
+Note: Currently it is not possible to build docs on Windows without using a Unix-on-Windows layer such as MSYS2 MINGW32.

diff --git a/docs/conf_common.py b/docs/conf_common.py
index 0eafe710db3b81ee3199fb47dbcc7cc2ddda473c..44bd4282bb71eeeef6536f4903d79cce2344ccc3 100644 (file)
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -56,25 +56,36 @@ copy_if_modified('xml/', 'xml_in/')
 # Generate 'api_name.inc' files using the XML files by Doxygen
 call_with_python('../gen-dxd.py')
 
+def find_component_files(parent_dir, target_filename):
+    parent_dir = os.path.abspath(parent_dir)
+    result = []
+    for (dirpath, dirnames, filenames) in os.walk(parent_dir):
+        try:
+            # note: trimming "examples" dir as MQTT submodule
+            # has its own examples directory in the submodule, not part of IDF
+            dirnames.remove("examples")
+        except ValueError:
+            pass
+        if target_filename in filenames:
+            result.append(os.path.join(dirpath, target_filename))
+    print("List of %s: %s" % (target_filename, ", ".join(result)))
+    return result
+
 # Generate 'kconfig.inc' file from components' Kconfig files
 print("Generating kconfig.inc from kconfig contents")
 kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
 temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
-# note: trimming "examples" dir from KConfig/KConfig.projbuild as MQTT submodule
-# has its own examples in the submodule.
-kconfigs = subprocess.check_output(["find", "../../components",
-                                    "-name", "examples", "-prune",
-                                    "-o", "-name", "Kconfig", "-print"]).decode()
-kconfig_projbuilds = subprocess.check_output(["find", "../../components",
-                                              "-name", "examples", "-prune",
-                                              "-o", "-name", "Kconfig.projbuild", "-print"]).decode()
+
+kconfigs = find_component_files("../../components", "Kconfig")
+kconfig_projbuilds = find_component_files("../../components", "Kconfig.projbuild")
+
 confgen_args = [sys.executable,
                 "../../tools/kconfig_new/confgen.py",
                 "--kconfig", "../../Kconfig",
                 "--config", temp_sdkconfig_path,
                 "--create-config-if-missing",
-                "--env", "COMPONENT_KCONFIGS={}".format(kconfigs),
-                "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(kconfig_projbuilds),
+                "--env", "COMPONENT_KCONFIGS={}".format(" ".join(kconfigs)),
+                "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)),
                 "--env", "IDF_PATH={}".format(idf_path),
                 "--output", "docs", kconfig_inc_path + '.in'
 ]