docs: Move version-related includes to run in sphinx-build not make

[esp-idf] / docs / conf_common.py

diff --git a/docs/conf_common.py b/docs/conf_common.py
index 1654a1ea82e26dafda4ead99ab62e7b057cf1b5d..188acf657ac7e57b597cebb37aa25a3dfdf7ca8e 100644 (file)
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -31,20 +31,42 @@ if 'BUILDDIR' in os.environ:
     builddir = os.environ['BUILDDIR']
 
 # Call Doxygen to get XML files from the header files
-print "Calling Doxygen to generate latest XML files"
-os.system("doxygen ../Doxyfile")
+print("Calling Doxygen to generate latest XML files")
+if os.system("doxygen ../Doxyfile") != 0:
+    raise RuntimeError('Doxygen call failed')
+
 # Doxygen has generated XML files in 'xml' directory.
 # Copy them to 'xml_in', only touching the files which have changed.
 copy_if_modified('xml/', 'xml_in/')
 
 # Generate 'api_name.inc' files using the XML files by Doxygen
-os.system('python ../gen-dxd.py')
+if os.system('python ../gen-dxd.py') != 0:
+    raise RuntimeError('gen-dxd.py failed')
 
 # Generate 'kconfig.inc' file from components' Kconfig files
 kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
-os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in')
+if os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in') != 0:
+    raise RuntimeError('gen-kconfig-doc.py failed')
+
 copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
 
+# Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions
+esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(builddir)
+if os.system('python ../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in') != 0:
+    raise RuntimeError('gen_esp_err_to_name.py failed')
+copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path)
+
+# Generate version-related includes
+#
+# (Note: this is in a function as it needs to access configuration to get the language)
+def generate_version_specific_includes(app):
+    print("Generating version-specific includes...")
+    version_tmpdir = '{}/version_inc'.format(builddir)
+    if os.system('python ../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir)):
+        raise RuntimeError('gen-version-specific-includes.py failed')
+    copy_if_modified(version_tmpdir, '{}/inc'.format(builddir))
+
+
 # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
 # 
 suppress_warnings = ['image.nonlocal_uri']
@@ -115,7 +137,7 @@ version = run_cmd_get_output('git describe')
 # The full version, including alpha/beta/rc tags.
 # If needed, nearest tag is returned by 'git describe --abbrev=0'.
 release = version
-print 'Version: {0}  Release: {1}'.format(version, release)
+print('Version: {0}  Release: {1}'.format(version, release))
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -175,7 +197,7 @@ html_theme = 'default'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = "../_static/espressif-logo.svg"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -185,7 +207,7 @@ html_theme = 'default'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['../_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -327,3 +349,9 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # otherwise, readthedocs.org uses their theme by default, so no need to specify it
+
+# Override RTD CSS theme to introduce the theme corrections
+# https://github.com/rtfd/sphinx_rtd_theme/pull/432
+def setup(app):
+    app.add_stylesheet('theme_overrides.css')
+    generate_version_specific_includes(app)