Adjust 'make docs' to do an incremental build

compiler/Makefile

@@ -147,11 +147,11 @@ $(CHPL_MAKE_HOME)/configured-prefix:
 
 $(CONFIGURED_PREFIX_FILE): FORCE $(COMPILER_BUILD) $(CHPL_MAKE_HOME)/configured-prefix
 	@echo '"'`cat $(CHPL_MAKE_HOME)/configured-prefix`'"' \ > $(CONFIGURED_PREFIX_FILE).incoming
-	@$(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different $(CONFIGURED_PREFIX_FILE) $(CONFIGURED_PREFIX_FILE).incoming
+	@$(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different --update $(CONFIGURED_PREFIX_FILE) $(CONFIGURED_PREFIX_FILE).incoming
 
 $(CLANG_SETTINGS_FILE): FORCE $(COMPILER_BUILD)
 	@echo '{"'$(CLANG_CC)'","'$(CLANG_CXX)'","'`$(CHPL_MAKE_HOME)/util/config/gather-clang-sysroot-arguments $(CLANG_CC)`'"}' | $(FIXPATH_CMD) > $(CLANG_SETTINGS_FILE).incoming
-	@$(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different $(CLANG_SETTINGS_FILE) $(CLANG_SETTINGS_FILE).incoming
+	@$(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different --update $(CLANG_SETTINGS_FILE) $(CLANG_SETTINGS_FILE).incoming
 
 $(CHPL_CONFIG_CHECK): | $(CHPL_BIN_DIR)
 	rm -rf $(CHPL_CONFIG_CHECK_PREFIX)

doc/Makefile

@@ -20,14 +20,22 @@ include Makefile.sphinx
 CHPLDEPS = $(shell $(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/chplenv/chpl_home_utils.py --chpldeps)
 
 CHPL2RST = $(CHPL_MAKE_PYTHON) $(CHPLDEPS) ./util/chpl2rst.py
+COPY_IF_DIFFERENT = $(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different --copy
 
-CHPL_DOC_PRIMERS_DIR = $(SOURCEDIR)/primers
-CHPL2RSTOPTS = --output=rst --prefix=$(CHPL_DOC_PRIMERS_DIR) --link=$(WEB_DOC_DIR)$(WEB_DOC_VERSION)
 
-CHPL_DOC_HELLO_DIR = $(SOURCEDIR)/examples/hellos
-CHPL2RSTOPTS_HELLO = --output=rst --prefix=$(CHPL_DOC_HELLO_DIR) --link=$(WEB_DOC_DIR)$(WEB_DOC_VERSION)
+CHPL_DOC_PRIMERS_BUILD_DIR = ../build/doc/primers
+CHPL_DOC_PRIMERS_RST_DIR = $(SOURCEDIR)/primers
+CHPL2RSTOPTS = --output=rst --prefix=$(CHPL_DOC_PRIMERS_BUILD_DIR) --link=$(WEB_DOC_DIR)$(WEB_DOC_VERSION)
 
-SPECSRCDIR = $(SOURCEDIR)/language/spec
+CHPL_DOC_EXAMPLES_BUILD_DIR = ../build/doc/examples
+CHPL_DOC_EXAMPLES_RST_DIR = $(SOURCEDIR)/examples
+
+CHPL_DOC_HELLO_BUILD_DIR = $(CHPL_DOC_EXAMPLES_BUILD_DIR)/hellos
+CHPL_DOC_HELLO_RST_DIR = $(CHPL_DOC_EXAMPLES_RST_DIR)/hellos
+CHPL2RSTOPTS_HELLO = --output=rst --prefix=$(CHPL_DOC_HELLO_BUILD_DIR) --link=$(WEB_DOC_DIR)$(WEB_DOC_VERSION)
+
+SPEC_BUILD_DIR = ../build/doc/language/spec
+SPEC_RST_DIR = $(SOURCEDIR)/language/spec
 
 help: help-sphinx help-source
 
@@ -38,7 +46,7 @@ help-source:
 	@echo "  man-chapel     to invoke 'make man'"
 	@echo "  module-docs    to invoke 'make documentation' in ../modules"
 	@echo "  primers        to generate primer docs in $(SOURCEDIR)/primers/"
-	@echo "  hellos         to generate hellos docs in $(SOURCEDIR)/examples/"
+	@echo "  examples       to generate hellos docs in $(SOURCEDIR)/examples/"
 	@echo "  symlinks       to create symlinks from ../man and ../test"
 	@echo "  clean          to remove all generated files excluding ../build/doc"
 	@echo "  clean-build    to remove all generated files in ../build/doc"
@@ -54,45 +62,58 @@ man-chapel: FORCE
 	$(MAKE) man
 
 
-source: collect-syntax module-docs primers hellos symlinks
+source: collect-syntax module-docs primers examples symlinks
 
 
-collect-syntax: clean-collect-syntax
+collect-syntax:
 	@echo
-	@echo "Collecting syntax from '$(SPECSRCDIR)' into '$(SPECSRCDIR)/syntax.rst'"
-	./util/collect-syntax.py rst/language/spec --outdir $(SPECSRCDIR)
+	@echo "Collecting syntax from '$(SPEC_RST_DIR)' into '$(SPEC_RST_DIR)/syntax.rst'"
+	@mkdir -p $(SPEC_BUILD_DIR)
+	@touch $(SPEC_BUILD_DIR)/syntax.rst
+	@./util/collect-syntax.py rst/language/spec --outdir $(SPEC_BUILD_DIR)
+	@$(COPY_IF_DIFFERENT) "$(SPEC_BUILD_DIR)/syntax.rst" "$(SPEC_RST_DIR)/syntax.rst"
 
-module-docs: clean-module-docs
+module-docs:
 	@echo
 	@echo "Generating module docs from "'$$CHPL_HOME'"/modules/ into $(SOURCEDIR)/modules"
-	(cd ../modules && $(MAKE) documentation)
-	cp -f $(SOURCEDIR)/meta/modules/* $(SOURCEDIR)/modules/
-	cp -f $(SOURCEDIR)/meta/builtins/* $(SOURCEDIR)/builtins/
+	@# modules/Makefile will
+	@#   store module docs in doc/rst/modules and doc/rst/builtins
+	@#   including meta/modules/* and meta/builtins/*
+	@(cd ../modules && $(MAKE) documentation)
 
-primers: clean-primers
+primers:
 	@echo
 	@echo "Generating primers from "'$$CHPL_HOME'"/test/release/examples to $(SOURCEDIR)/primers"
+	@rm -rf $(CHPL_DOC_PRIMERS_BUILD_DIR)
+	@mkdir -p $(CHPL_DOC_PRIMERS_BUILD_DIR)
 	@#Note - this assumes that we are not in a release tar ball
-	$(CHPL2RST) $(CHPL2RSTOPTS) ../test/release/examples/primers/*.chpl
-	$(CHPL2RST) $(CHPL2RSTOPTS) ../test/release/examples/primers/*doc.chpl --codeblock
-	cp -f $(SOURCEDIR)/meta/primers/* $(SOURCEDIR)/primers
+	@$(CHPL2RST) $(CHPL2RSTOPTS) ../test/release/examples/primers/*.chpl
+	@$(CHPL2RST) $(CHPL2RSTOPTS) ../test/release/examples/primers/*doc.chpl --codeblock
+	@mkdir -p $(CHPL_DOC_PRIMERS_RST_DIR)
+	@cp -f $(SOURCEDIR)/meta/primers/* $(CHPL_DOC_PRIMERS_BUILD_DIR)
+	@$(COPY_IF_DIFFERENT) $(CHPL_DOC_PRIMERS_BUILD_DIR) $(CHPL_DOC_PRIMERS_RST_DIR)
+
 
-hellos: clean-hellos
+examples:
 	@echo
 	@echo "Generating hellos from "'$$CHPL_HOME'"/test/release/examples to $(SOURCEDIR)/examples"
-	$(CHPL2RST) $(CHPL2RSTOPTS_HELLO) ../examples/hello*.chpl
-	cp -f $(SOURCEDIR)/meta/examples/* $(SOURCEDIR)/examples
-
-symlinks: clean-symlinks
+	@rm -rf $(CHPL_DOC_EXAMPLES_BUILD_DIR)
+	@mkdir -p $(CHPL_DOC_EXAMPLES_BUILD_DIR)
+	@$(CHPL2RST) $(CHPL2RSTOPTS_HELLO) ../examples/hello*.chpl
+	@cp -f $(SOURCEDIR)/meta/examples/* $(CHPL_DOC_EXAMPLES_BUILD_DIR)
+	@mkdir -p $(CHPL_DOC_EXAMPLES_RST_DIR)
+	@$(COPY_IF_DIFFERENT) $(CHPL_DOC_EXAMPLES_BUILD_DIR) $(CHPL_DOC_EXAMPLES_RST_DIR)
+
+symlinks:
 	@echo
 	@echo "Creating symlinks"
-	ln -s $$CHPL_HOME/man/chpl.rst $(SOURCEDIR)/usingchapel/man.rst
-	ln -s $$CHPL_HOME/man/chpldoc.rst $(SOURCEDIR)/tools/chpldoc/man.rst
-	ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/tools/chplvis/examples
-	ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/base/examples
-	ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/taskpar/examples
-	ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/datapar/examples
-	ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/locality/examples
+	@if [ ! -e $(SOURCEDIR)/usingchapel/man.rst ]; then ln -s $$CHPL_HOME/man/chpl.rst $(SOURCEDIR)/usingchapel/man.rst; fi
+	@if [ ! -e $(SOURCEDIR)/tools/chpldoc/man.rst ]; then ln -s $$CHPL_HOME/man/chpldoc.rst $(SOURCEDIR)/tools/chpldoc/man.rst; fi
+	@if [ ! -e $(SOURCEDIR)/tools/chplvis/examples ]; then ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/tools/chplvis/examples; fi
+	@if [ ! -e $(SOURCEDIR)/users-guide/base/examples ]; then ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/base/examples; fi
+	@if [ ! -e $(SOURCEDIR)/users-guide/taskpar/examples ]; then ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/taskpar/examples; fi
+	@if [ ! -e $(SOURCEDIR)/users-guide/datapar/examples ]; then ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/datapar/examples; fi
+	@if [ ! -e $(SOURCEDIR)/users-guide/locality/examples ]; then ln -s $$CHPL_HOME/test/release/examples $(SOURCEDIR)/users-guide/locality/examples; fi
 
 checkdocs: FORCE
 	$(MAKE) check
@@ -109,18 +130,21 @@ prunedocs: FORCE
 	fi
 
 
-clean: clean-source
+clean: clean-source clean-build clean-build-dir
+
+cleanall: clean-source clean-build clean-build-dir
 
-cleanall: clean-source
+clobber: clean-source clean-build clean-build-dir
 
-clobber: clean-source clean-build
+clean-source: clean-module-docs clean-primers clean-examples clean-symlinks clean-collect-syntax
 
-clean-source: clean-module-docs clean-primers clean-hellos clean-symlinks
+clean-build-dir: FORCE
+	rm -rf ../build/doc
 
 clean-collect-syntax: FORCE
 	@echo
 	@echo "Removing generated RST file for syntax productions"
-	touch $(SPECSRCDIR)/syntax.rst && rm $(SPECSRCDIR)/syntax.rst
+	touch $(SPEC_RST_DIR)/syntax.rst && rm $(SPEC_RST_DIR)/syntax.rst
 
 clean-module-docs: FORCE
 	@echo
@@ -133,7 +157,7 @@ clean-primers: FORCE
 	@echo "Removing primers generated into $(CHPL_DOC_HELLO_DIR)"
 	rm -rf $(SOURCEDIR)/primers/
 
-clean-hellos: FORCE
+clean-examples: FORCE
 	@echo
 	@echo "Removing hellos generated into $(CHPL_DOC_HELLO_DIR)"
 	rm -rf $(SOURCEDIR)/examples/

doc/Makefile.sphinx

@@ -5,7 +5,7 @@ export CHPL_MAKE_PYTHON := $(shell $(CHPL_MAKE_HOME)/util/config/find-python.sh)
 endif
 
 CHPLDEPS = $(shell $(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/chplenv/chpl_home_utils.py --chpldeps)
-
+COPY_IF_DIFFERENT = $(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different --copy
 
 # You can set these variables from the command line.
 SPHINXOPTS    = -W -n
@@ -78,14 +78,15 @@ check-sphinxbuild:
 	  exit 1 ; \
 	fi
 
-html-release: check-sphinxbuild source clean-build
+html-release: check-sphinxbuild source
 	@echo
 	@echo "Building HTML documentation"
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@chmod -R ugo+rX $(BUILDDIR)
-	cp util/versionButton.php $(BUILDDIR)/html/
+	@$(COPY_IF_DIFFERENT) util/versionButton.php $(BUILDDIR)/html/versionButton.php
 	@echo "ErrorDocument 404 https://chapel-lang.org/docs/$(WEB_DOC_VERSION)/index.html" > $(BUILDDIR)/html/.htaccess
-	mv $(BUILDDIR)/html .
+	@rm -Rf html
+	@cp -R $(BUILDDIR)/html html
 	@echo
 	@echo "Build finished. The HTML pages are in "'$$CHPL_HOME'"/doc/html."
 
@@ -100,7 +101,7 @@ html-dev:
 	@echo
 	@echo "Build finished. The HTML pages are in ./html."
 
-html: check-sphinxbuild source clean-build
+html: check-sphinxbuild source
 	@echo
 	@echo "Building HTML documentation"
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -111,41 +112,41 @@ html: check-sphinxbuild source clean-build
 %.html: FORCE
 	$(SPHINXBUILD) . build/html/$* && chmod -R ugo+rX build
 
-check: check-sphinxbuild source clean-build
+check: check-sphinxbuild source
 	@echo "Checking for broken links or cross-references"
 	$(SPHINXBUILD) -n -b linkcheck -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/linkcheck
 	@chmod -R ugo+rX $(BUILDDIR)
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in "'$(BUILDPATH)'"/linkcheck/output.txt."
 
-dirhtml: check-sphinxbuild source clean-build
+dirhtml: check-sphinxbuild source
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in "'$(BUILDPATH)'"/dirhtml."
 
-singlehtml: check-sphinxbuild source clean-build
+singlehtml: check-sphinxbuild source
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in "'$(BUILDPATH)'"/singlehtml."
 
-pickle: check-sphinxbuild source clean-build
+pickle: check-sphinxbuild source
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json: check-sphinxbuild source clean-build
+json: check-sphinxbuild source
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: check-sphinxbuild source clean-build
+htmlhelp: check-sphinxbuild source
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in "'$(BUILDPATH)'"/htmlhelp."
 
-qthelp: check-sphinxbuild source clean-build
+qthelp: check-sphinxbuild source
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -154,31 +155,31 @@ qthelp: check-sphinxbuild source clean-build
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/chpldoc.qhc"
 
-latex: check-sphinxbuild source clean-build
+latex: check-sphinxbuild source
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in "'$(BUILDPATH)'"/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf: check-sphinxbuild source clean-build
+latexpdf: check-sphinxbuild source
 	$(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 "'$(BUILDPATH)'"/latex."
 
-latexpdfja: check-sphinxbuild source clean-build
+latexpdfja: check-sphinxbuild source
 	$(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 "'$(BUILDPATH)'"/latex."
 
-text: check-sphinxbuild source clean-build
+text: check-sphinxbuild source
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in "'$(BUILDPATH)'"/text."
 
-man: check-sphinxbuild source clean-build
+man: check-sphinxbuild source
 	@echo
 	@echo "Building man page documentation"
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@@ -188,41 +189,41 @@ man: check-sphinxbuild source clean-build
 	@echo
 	@echo "Build finished. The manual pages are in "'$(BUILDPATH)'"/man."
 
-texinfo: check-sphinxbuild source clean-build
+texinfo: check-sphinxbuild source
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in "'$(BUILDPATH)'"/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
-info: check-sphinxbuild source clean-build
+info: check-sphinxbuild source
 	$(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 "'$(BUILDPATH)'"/texinfo."
 
-gettext: check-sphinxbuild source clean-build
+gettext: check-sphinxbuild source
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in "'$(BUILDPATH)'"/locale."
 
-changes: check-sphinxbuild source clean-build
+changes: check-sphinxbuild source
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in "'$(BUILDPATH)'"/changes."
 
-linkcheck: check-sphinxbuild source clean-build
+linkcheck: check-sphinxbuild source
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in "'$(BUILDPATH)'"/linkcheck/output.txt."
 
-xml: check-sphinxbuild source clean-build
+xml: check-sphinxbuild source
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in "'$(BUILDPATH)'"/xml."
 
-pseudoxml: check-sphinxbuild source clean-build
+pseudoxml: check-sphinxbuild source
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in "'$(BUILDPATH)'"/pseudoxml."