From 92b29923cb7707792534e032fcb3a2e3fb4f9f4f Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 13 Aug 2018 12:24:55 +1000 Subject: [PATCH] docs: Move version-related includes to run in sphinx-build not make Means they show up on ReadTheDocs(!) --- docs/conf_common.py | 12 ++++++ docs/docs_common.mk | 61 ++++++++++++++------------- docs/gen-version-specific-includes.py | 4 +- 3 files changed, 45 insertions(+), 32 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index 474653235..56a08806f 100644 --- 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 4b125ac74..85056dc39 100644 --- 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 b435e0aa9..a295e4b6a 100755 --- 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]