{"action":"created","issue":{"url":"https://api.github.com/repos/apache/spark/issues/21659","repository_url":"https://api.github.com/repos/apache/spark","labels_url":"https://api.github.com/repos/apache/spark/issues/21659/labels{/name}","comments_url":"https://api.github.com/repos/apache/spark/issues/21659/comments","events_url":"https://api.github.com/repos/apache/spark/issues/21659/events","html_url":"https://github.com/apache/spark/pull/21659","id":336706608,"node_id":"MDExOlB1bGxSZXF1ZXN0MTk4MDk1OTQ5","number":21659,"title":"[SPARK-24530][PYTHON] Add a control to force Python version in Sphinx via environment variable, SPHINXPYTHON","user":{"login":"HyukjinKwon","id":6477701,"node_id":"MDQ6VXNlcjY0Nzc3MDE=","avatar_url":"https://avatars0.githubusercontent.com/u/6477701?v=4","gravatar_id":"","url":"https://api.github.com/users/HyukjinKwon","html_url":"https://github.com/HyukjinKwon","followers_url":"https://api.github.com/users/HyukjinKwon/followers","following_url":"https://api.github.com/users/HyukjinKwon/following{/other_user}","gists_url":"https://api.github.com/users/HyukjinKwon/gists{/gist_id}","starred_url":"https://api.github.com/users/HyukjinKwon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/HyukjinKwon/subscriptions","organizations_url":"https://api.github.com/users/HyukjinKwon/orgs","repos_url":"https://api.github.com/users/HyukjinKwon/repos","events_url":"https://api.github.com/users/HyukjinKwon/events{/privacy}","received_events_url":"https://api.github.com/users/HyukjinKwon/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":4,"created_at":"2018-06-28T17:10:56Z","updated_at":"2018-06-28T17:54:55Z","closed_at":null,"author_association":"MEMBER","pull_request":{"url":"https://api.github.com/repos/apache/spark/pulls/21659","html_url":"https://github.com/apache/spark/pull/21659","diff_url":"https://github.com/apache/spark/pull/21659.diff","patch_url":"https://github.com/apache/spark/pull/21659.patch"},"body":"## What changes were proposed in this pull request?\r\n\r\nThis PR proposes to add `SPHINXPYTHON` environment variable to control the Python version used by Sphinx.\r\n\r\nThe motivation of this environment variable is, it seems not properly rendering some signatures in the Python documentation when Python 2 is used by Sphinx. See the JIRA's case. It should be encouraged to use Python 3, but looks we will probably live with this problem for a long while in any event.\r\n\r\nFor most cases of just normal `make html` where `python` is Python 2.x (for example simply for development purpose), the only difference should be one warning message:\r\n\r\n```\r\n$ make html\r\nMakefile:13: Note that Python 3 is required to generate PySpark documentation correctly for now. Current Python executable was less then Python 3. See SPARK-24530. To force Sphinx to use a specific Python executable, please set SPHINXPYTHON to point to the Python 3 executable.\r\npython -msphinx -b html -d _build/doctrees   . _build/html\r\nRunning Sphinx v1.7.5\r\n...\r\n```\r\n\r\nProbably, we can somehow work around this via explicitly setting `SPHINXBUILD` but `sphinx-build` can't be easily distinguished since it (at least in my environment and up to my knowledge) doesn't replace `sphinx-build` when newer Sphinx is installed in different Python version. It confuses.\r\n\r\n\r\n\r\n## How was this patch tested?\r\n\r\nManually tested:\r\n\r\n**`python` (Python 2.7) in the path with Sphinx:**\r\n\r\n```\r\n$ make html\r\nMakefile:13: Note that Python 3 is required to generate PySpark documentation correctly for now. Current Python executable was less then Python 3. See SPARK-24530. To force Sphinx to use a specific Python executable, please set SPHINXPYTHON to point to the Python 3 executable.\r\npython -msphinx -b html -d _build/doctrees   . _build/html\r\nRunning Sphinx v1.7.5\r\n...\r\n```\r\n\r\n**`python` (Python 2.7) in the path without Sphinx:**\r\n\r\n```\r\n$ make html\r\nMakefile:13: Note that Python 3 is required to generate PySpark documentation correctly for now. Current Python executable was less then Python 3. See SPARK-24530. To force Sphinx to use a specific Python executable, please set SPHINXPYTHON to point to the Python 3 executable.\r\nMakefile:17: *** Python executable 'python' did not have Sphinx installed. Make sure you have Sphinx installed, then set the SPHINXPYTHON environment variable to point to the Python executable having Sphinx installed. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/.  Stop.\r\n```\r\n\r\n\r\n**`SPHINXPYTHON` set `python3` with Sphinx:**\r\n\r\n```\r\n$ SPHINXPYTHON=python3 make html\r\npython3 -msphinx -b html -d _build/doctrees   . _build/html\r\nRunning Sphinx v1.7.5\r\n...\r\n```\r\n\r\n**`SPHINXPYTHON` set `python3` without Sphinx:**\r\n\r\n```\r\n$ SPHINXPYTHON=python3 make html\r\nMakefile:17: *** Python executable 'python3' did not have Sphinx installed. Make sure you have Sphinx installed, then set the SPHINXPYTHON environment variable to point to the Python executable having Sphinx installed. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/.  Stop.\r\n```\r\n\r\n\r\n**`SPHINXBUILD` set:**\r\n\r\n```\r\nSPHINXBUILD=sphinx-build make html\r\nsphinx-build -b html -d _build/doctrees   . _build/html\r\nRunning Sphinx v1.7.5\r\n...\r\n```\r\n\r\n\r\n**Both `SPHINXPYTHON` and `SPHINXBUILD` are set:**\r\n\r\n```\r\nSPHINXBUILD=sphinx-build SPHINXPYTHON=python make html\r\nsphinx-build -b html -d _build/doctrees   . _build/html\r\nRunning Sphinx v1.7.5\r\n...\r\n```\r\n"},"comment":{"url":"https://api.github.com/repos/apache/spark/issues/comments/401120219","html_url":"https://github.com/apache/spark/pull/21659#issuecomment-401120219","issue_url":"https://api.github.com/repos/apache/spark/issues/21659","id":401120219,"node_id":"MDEyOklzc3VlQ29tbWVudDQwMTEyMDIxOQ==","user":{"login":"AmplabJenkins","id":4031291,"node_id":"MDQ6VXNlcjQwMzEyOTE=","avatar_url":"https://avatars3.githubusercontent.com/u/4031291?v=4","gravatar_id":"","url":"https://api.github.com/users/AmplabJenkins","html_url":"https://github.com/AmplabJenkins","followers_url":"https://api.github.com/users/AmplabJenkins/followers","following_url":"https://api.github.com/users/AmplabJenkins/following{/other_user}","gists_url":"https://api.github.com/users/AmplabJenkins/gists{/gist_id}","starred_url":"https://api.github.com/users/AmplabJenkins/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/AmplabJenkins/subscriptions","organizations_url":"https://api.github.com/users/AmplabJenkins/orgs","repos_url":"https://api.github.com/users/AmplabJenkins/repos","events_url":"https://api.github.com/users/AmplabJenkins/events{/privacy}","received_events_url":"https://api.github.com/users/AmplabJenkins/received_events","type":"User","site_admin":false},"created_at":"2018-06-28T17:54:55Z","updated_at":"2018-06-28T17:54:55Z","author_association":"NONE","body":"Merged build finished. Test PASSed."}}
{"actor":{"display_login":"AmplabJenkins"}}