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

Means they show up on ReadTheDocs(!)

diff --git a/docs/conf_common.py b/docs/conf_common.py
index 560e4e63956498a71216c6023a6f7c5ab0e65750..188acf657ac7e57b597cebb37aa25a3dfdf7ca8e 100644 (file)
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -56,6 +56,17 @@ if os.system('python ../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err
     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']
@@ -343,3 +354,4 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # https://github.com/rtfd/sphinx_rtd_theme/pull/432
 def setup(app):
     app.add_stylesheet('theme_overrides.css')
+    generate_version_specific_includes(app)

diff --git a/docs/docs_common.mk b/docs/docs_common.mk
index 4b125ac74c7a1e5ee21d29da0063fe04f1527337..85056dc3944b9209ffee13e97313750069895159 100644 (file)
--- a/docs/docs_common.mk
+++ b/docs/docs_common.mk
@@ -5,6 +5,14 @@
 # NOTE: This makefile runs with cwd=either en or zh_CN subfolder, so this
 # (docs/) directory is '..' relative to it.
 
+# ************ IMPORTANT *****************
+#
+# ReadTheDocs DOES NOT USE THIS MAKEFILE,
+# so any behaviour additions must be
+# done via Sphinx Config not here
+#
+# ****************************************
+
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
@@ -53,41 +61,38 @@ help:
 clean:
        rm -rf $(BUILDDIR)/*
 
-# Add any dependencies for Sphinx code generation here
-dependencies: version-specific-includes
-
-html: dependencies
+html:
        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: dependencies
+dirhtml:
        $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml: dependencies
+singlehtml:
        $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
        @echo
        @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle: dependencies
+pickle:
        $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
        @echo
        @echo "Build finished; now you can process the pickle files."
 
-json: dependencies
+json:
        $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
        @echo
        @echo "Build finished; now you can process the JSON files."
 
-htmlhelp: dependencies
+htmlhelp:
        $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
        @echo
        @echo "Build finished; now you can run HTML Help Workshop with the" \
              ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp: dependencies
+qthelp:
        $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
        @echo
        @echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -96,7 +101,7 @@ qthelp: dependencies
        @echo "To view the help file:"
        @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc"
 
-devhelp: dependencies
+devhelp:
        $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
        @echo
        @echo "Build finished."
@@ -105,70 +110,70 @@ devhelp: dependencies
        @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
        @echo "# devhelp"
 
-epub: dependencies
+epub:
        $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
        @echo
        @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex: dependencies
+latex:
        $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
        @echo
        @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
        @echo "Run \`make' in that directory to run these through (pdf)latex" \
              "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf: dependencies
+latexpdf:
        $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
        @echo "Running LaTeX files through pdflatex..."
        $(MAKE) -C $(BUILDDIR)/latex all-pdf
        @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-latexpdfja: dependencies
+latexpdfja:
        $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
        @echo "Running LaTeX files through platex and dvipdfmx..."
        $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
        @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-text: dependencies
+text:
        $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
        @echo
        @echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man: dependencies
+man:
        $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
        @echo
        @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo: dependencies
+texinfo:
        $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
        @echo
        @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
        @echo "Run \`make' in that directory to run these through makeinfo" \
              "(use \`make info' here to do that automatically)."
 
-info: dependencies
+info:
        $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
        @echo "Running Texinfo files through makeinfo..."
        make -C $(BUILDDIR)/texinfo info
        @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
-gettext: dependencies
+gettext:
        $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
        @echo
        @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes: dependencies
+changes:
        $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
        @echo
        @echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck: dependencies
+linkcheck:
        $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
        @echo
        @echo "Link check complete; look for any errors in the above output " \
              "or in $(BUILDDIR)/linkcheck/output.txt."
 
-gh-linkcheck: dependencies
+gh-linkcheck:
        @echo "Checking for hardcoded GitHub links"
        @if (find ../ -name '*.rst' | xargs grep \
                'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw'\
@@ -192,21 +197,17 @@ gh-linkcheck: dependencies
        fi
        @echo "No hardcoded links found"
 
-doctest: dependencies
+doctest:
        $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
        @echo "Testing of doctests in the sources finished, look at the " \
              "results in $(BUILDDIR)/doctest/output.txt."
 
-xml: dependencies
+xml:
        $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
        @echo
        @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
-pseudoxml: dependencies
+pseudoxml:
        $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
        @echo
        @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-version-specific-includes:
-       mkdir -p $(BUILDDIR)/inc
-       ../gen-version-specific-includes.py $(LANGUAGE) $(BUILDDIR)/inc

diff --git a/docs/gen-version-specific-includes.py b/docs/gen-version-specific-includes.py
index b435e0aa9400a6d0ea50e63cb30e292311c7c866..a295e4b6a7d714708b936e6fb5eeb6afed7c9031 100755 (executable)
--- a/docs/gen-version-specific-includes.py
+++ b/docs/gen-version-specific-includes.py
@@ -102,8 +102,8 @@ def main():
     language = sys.argv[1]
     out_dir = sys.argv[2]
     if not os.path.exists(out_dir):
-        print("Output directory %s not found" % out_dir)
-        sys.exit(1)
+        print("Creating directory %s" % out_dir)
+        os.mkdir(out_dir)
 
     template = TEMPLATES[language]