alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'bugfix/doc_builds_windows' into 'master'

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

See merge request idf/esp-idf!3550
This commit is contained in:
Angus Gratton 2018-11-20 17:20:40 +08:00
commit c0298a5712
2 changed files with 36 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/README.md
View File

@ -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.

31
docs/conf_common.py
View File

@ -58,25 +58,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'
]