Merge pull request #16680 from mppf/fix-mac-os-x-make-docs

Fix mac os x make docs

Follow-up to PR #16644 and #16560

This PR is intended to solve problems with `make docs` on Mac OS X.

* Don't replace python3 symlinks on mac os x
  * Our python3-wrapper exists to tolerate a different python3 path (e.g.
    in the case of installation) but it causes problems with the Python
    wrapper used for Mac OS X frameworks (in cpython,
    Mac/Tools/pythonw.c). I suspect there is a bug with this framework
    wrapper however I don't have a small reproducer. Setting the
    `PYTHONEXECUTABLE` variable did not help. However, calling e.g.
    `/usr/local/Cellar/python@3.9/3.9.0_1/Frameworks/Python.framework/Versions/3.9/Resources/Python.app/Contents/MacOS/Python`
    from our python3-wrapper allowed it to work (since this bypasses the
    pythonw.c wrapper).

* Update Makefiles to avoid `touch sphinx-build` which confused the issue

Reviewed by @ronawho - thanks!

- [x] make docs on mac os x with brew python3
- [x] make docs on Ubuntu 20.04
- [x] make docs on SLES12

third-party/Makefile

@@ -86,8 +86,8 @@ test-venv: $(CHPL_VENV_TEST_REQS)
 $(CHPL_VENV_TEST_REQS): $(CHPL_VENV_TEST_REQUIREMENTS_FILE)
 	cd chpl-venv && $(MAKE) test-venv
 
-chpldoc-venv: $(CHPL_VENV_SPHINX_BUILD)
-$(CHPL_VENV_SPHINX_BUILD): $(CHPL_VENV_CHPLDOC_REQUIREMENTS_FILE)
+chpldoc-venv: $(CHPL_VENV_CHPLDOC_REQS)
+$(CHPL_VENV_CHPLDOC_REQS): $(CHPL_VENV_CHPLDOC_REQUIREMENTS_FILE)
 	cd chpl-venv && $(MAKE) chpldoc-venv
 
 c2chapel-venv: $(CHPL_VENV_C2CHAPEL_REQS)

third-party/chpl-venv/Makefile

@@ -79,9 +79,11 @@ $(CHPL_VENV_VIRTUALENV_DIR):
 	export VIRTUAL_ENV=$(CHPL_VENV_VIRTUALENV_DIR) && \
 	$(PIP) install \
 	--upgrade $(CHPL_PIP_INSTALL_PARAMS) $(LOCAL_PIP_FLAGS) wheel && \
-	rm -f $(CHPL_VENV_VIRTUALENV_BIN)/python3 && \
-	cp python3-wrapper $(CHPL_VENV_VIRTUALENV_BIN)/python3 && \
 	touch $(CHPL_VENV_VIRTUALENV_DIR)
+	if [ "$(CHPL_MAKE_PLATFORM)" != "darwin" ] ; then \
+	  rm -f $(CHPL_VENV_VIRTUALENV_BIN)/python3 && \
+	  cp python3-wrapper $(CHPL_VENV_VIRTUALENV_BIN)/python3 ; \
+	fi
 
 # Phony convenience target for creating virtualenv.
 create-virtualenv: $(CHPL_VENV_VIRTUALENV_DIR)
@@ -98,31 +100,31 @@ create-virtualenv: $(CHPL_VENV_VIRTUALENV_DIR)
 #   /bin/sh: .../path/to/bin/pip: <truncated hash bang>: bad interpreter: No such file or directory.
 #
 # By calling `python .../path/to/pip ...`, this issue is circumvented.
-$(CHPL_VENV_TEST_REQS): $(CHPL_VENV_VIRTUALENV_DIR)
+$(CHPL_VENV_TEST_REQS): $(CHPL_VENV_VIRTUALENV_DIR) test-requirements.txt
 	export PYTHONPATH="$(PIPLIBS):$$PYTHONPATH" && \
 	export PATH="$(CHPL_VENV_VIRTUALENV_BIN):$$PATH" && \
 	export VIRTUAL_ENV=$(CHPL_VENV_VIRTUALENV_DIR) && \
 	$(PIP) install \
 	--upgrade $(CHPL_PIP_INSTALL_PARAMS) $(LOCAL_PIP_FLAGS) -r test-requirements.txt && \
 	touch $(CHPL_VENV_TEST_REQS)
 
-$(CHPL_VENV_SPHINX_BUILD): $(CHPL_VENV_VIRTUALENV_DIR)
+$(CHPL_VENV_CHPLDOC_REQS): $(CHPL_VENV_VIRTUALENV_DIR) chpldoc-requirements.txt
 	export PYTHONPATH="$(PIPLIBS):$$PYTHONPATH" && \
 	export PATH="$(CHPL_VENV_VIRTUALENV_BIN):$$PATH" && \
 	export VIRTUAL_ENV=$(CHPL_VENV_VIRTUALENV_DIR) && \
 	$(PIP) install \
 	--upgrade $(CHPL_PIP_INSTALL_PARAMS) $(LOCAL_PIP_FLAGS) -r chpldoc-requirements.txt && \
-	touch $(CHPL_VENV_SPHINX_BUILD)
+	touch $(CHPL_VENV_CHPLDOC_REQS)
 
-$(CHPL_VENV_C2CHAPEL_REQS): $(CHPL_VENV_VIRTUALENV_DIR)
+$(CHPL_VENV_C2CHAPEL_REQS): $(CHPL_VENV_VIRTUALENV_DIR) c2chapel-requirements.txt
 	export PYTHONPATH="$(PIPLIBS):$$PYTHONPATH" && \
 	export PATH="$(CHPL_VENV_VIRTUALENV_BIN):$$PATH" && \
 	export VIRTUAL_ENV=$(CHPL_VENV_VIRTUALENV_DIR) && \
 	$(PIP) install \
 	--upgrade $(CHPL_PIP_INSTALL_PARAMS) $(LOCAL_PIP_FLAGS) -r c2chapel-requirements.txt && \
 	touch $(CHPL_VENV_C2CHAPEL_REQS)
 
-$(CHPL_VENV_CHPLSPELL_REQS): $(CHPL_VENV_VIRTUALENV_DIR)
+$(CHPL_VENV_CHPLSPELL_REQS): $(CHPL_VENV_VIRTUALENV_DIR) chplspell-requirements.txt
 	export PYTHONPATH="$(PIPLIBS):$$PYTHONPATH" && \
 	export PATH="$(CHPL_VENV_VIRTUALENV_BIN):$$PATH" && \
 	export VIRTUAL_ENV=$(CHPL_VENV_VIRTUALENV_DIR) && \
@@ -132,22 +134,22 @@ $(CHPL_VENV_CHPLSPELL_REQS): $(CHPL_VENV_VIRTUALENV_DIR)
 
 test-venv: $(CHPL_VENV_TEST_REQS)
 
-chpldoc-venv: $(CHPL_VENV_SPHINX_BUILD)
+chpldoc-venv: $(CHPL_VENV_CHPLDOC_REQS)
 
 c2chapel-venv: $(CHPL_VENV_C2CHAPEL_REQS)
 
 chplspell-venv: $(CHPL_VENV_CHPLSPELL_REQS)
 
 # Phony convenience target for install python packages.
-install-requirements: rm-test-reqs rm-sphinx-build $(CHPL_VENV_TEST_REQS) $(CHPL_VENV_SPHINX_BUILD) $(CHPL_VENV_CHPLSPELL_REQS)
+install-requirements: rm-test-reqs rm-chpldoc-reqs $(CHPL_VENV_TEST_REQS) $(CHPL_VENV_CHPLDOC_REQS) $(CHPL_VENV_CHPLSPELL_REQS)
 
 # Remove chpl-test-reqs, forcing install-requirements to be rebuilt.
 rm-test-reqs: FORCE
 	@rm -f $(CHPL_VENV_TEST_REQS)
 
-# Remove sphinx-build, forcing install-requirements to be rebuilt.
-rm-sphinx-build: FORCE
-	@rm -f $(CHPL_VENV_SPHINX_BUILD)
+# Remove chpldoc-reqs, forcing install-requirements to be rebuilt.
+rm-chpldoc-reqs: FORCE
+	@rm -f $(CHPL_VENV_CHPLDOC_REQS)
 
 # Remove chplspell-reqs, forcing install-requirements to be rebuilt.
 rm-chplspell-reqs: FORCE
@@ -161,6 +163,6 @@ use-system-python: FORCE
 
 FORCE:
 
-.PHONY: install-requirements create-virtualenv virtualenv check-exes rm-sphinx-build check-pip check-python
+.PHONY: install-requirements create-virtualenv virtualenv check-exes rm-chpldoc-reqs check-pip check-python
 
 .NOTPARALLEL:

third-party/chpl-venv/Makefile.include

@@ -31,10 +31,10 @@ CHPL_VENV_VIRTUALENV_NAME=chpl-virtualenv
 CHPL_VENV_VIRTUALENV_SUBDIR=$(CHPL_VENV_INSTALL_SUBDIR)/$(CHPL_VENV_VIRTUALENV_NAME)
 CHPL_VENV_VIRTUALENV_DIR=$(CHPL_VENV_DIR)/$(CHPL_VENV_VIRTUALENV_SUBDIR)
 CHPL_VENV_VIRTUALENV_BIN=$(CHPL_VENV_VIRTUALENV_DIR)/bin
-CHPL_VENV_SPHINX_BUILD=$(CHPL_VENV_VIRTUALENV_BIN)/sphinx-build
 
 # note - run-in-test-venv.bash also uses this path
 CHPL_VENV_TEST_REQS=$(CHPL_VENV_VIRTUALENV_DIR)/chpl-test-reqs
+CHPL_VENV_CHPLDOC_REQS=$(CHPL_VENV_VIRTUALENV_DIR)/chpldoc-reqs
 CHPL_VENV_C2CHAPEL_REQS=$(CHPL_VENV_VIRTUALENV_DIR)/c2chapel-reqs
 CHPL_VENV_CHPLSPELL_REQS=$(CHPL_VENV_VIRTUALENV_DIR)/chpl-chplspell-reqs