Skip to content

Commit

Permalink
Merge pull request #16835 from mppf/make-docs-incremental
Browse files Browse the repository at this point in the history 
Adjust 'make docs' to do an incremental build

Resolves #16826

Note, #16862 /
chapel-lang/sphinxcontrib-chapeldomain#45 is
required for this change to function properly - but this branch has those
changes.

This PR adjusts `make docs` to do an incremental sphinx build. For now,
the `chpldoc` command always runs, but the scripts only update the source
files for `sphinx-build` if they are different.

This brings a `make docs` after a minor change to about 10 seconds.

Details:
 * Adjusts `util/config/update-if-different` to include a mode argument
   (`--update` or `--copy`) and adjusts the existing calls to it to use
   the `--update` argument.
 * Added `--copy` mode to `util/config/update-if-different` that will
   copy all updated source files (recursively) and delete things in the
   dst directory not present in src.
 * Does the module docs build steps by first constructing the rst sources
   in a subdirectory of build/doc/ and then using `update-if-different
   --copy` from here (so that removed files can be correctly handled)
 * Updated Makefiles for `make docs` to avoid deleting "build" directory
   (since we can use it again, incrementally)
 * Removes a lot of command echoing for this process. One can use `make
   SHELL='sh -x' docs` to see the commands again.

Reviewed by @ben-albrecht and @lydia-duncan - thanks!

- [x] full local testing
  • Loading branch information
@mppf
mppf committed Dec 14, 2020
2 parents 387505e + 5ae40a1 commit 06cf289
Show file tree
Hide file tree
Showing 6 changed files with 207 additions and 92 deletions.
4 changes: 2 additions & 2 deletions compiler/Makefile
View file
Expand Up @@ -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)
Expand Down
96 changes: 60 additions & 36 deletions doc/Makefile
View file
Expand Up @@ -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

Expand All @@ -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"
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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/
Expand Down
49 changes: 25 additions & 24 deletions doc/Makefile.sphinx
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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."

Expand All @@ -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
Expand All @@ -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" \
Expand All @@ -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
Expand All @@ -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."
Expand Down

0 comments on commit 06cf289

Please sign in to comment.