RFC: Fix for sphinx setup message

From: Bird, Tim
Date: Fri Feb 21 2020 - 17:15:42 EST


(Resend: Sorry for the dup. I forgot to include the maintainers, and I had the LKML
address wrong.)

I was trying to set up my machine to do some documentation work,
and I had some problems with the sphinx install. I figured out how to work
around the issue, but I have a question about how to add the information
to scripts/sphinx-pre-install (or whether it should go somewhere else).

Detailed messages below, but the TLl;DR is that I got the message:
-------
You should run:

sudo apt-get install dvipng fonts-noto-cjk latexmk librsvg2-bin texlive-xetex
/usr/bin/virtualenv sphinx_1.7.9
. sphinx_1.7.9/bin/activate
pip install -r ./Documentation/sphinx/requirements.txt
...
------

The pip install step didn't work, and I found that I needed to have everything
based on python3 instead. When I replaced:
/usr/bin/virtualenv sphinx_1.7.9
with
/usr/bin/virtualenv -p python3 sphinx_1.7.9
everything worked.

This message is coming from scripts/sphinx-pre-install (I believe on line 708).

Should I go ahead and submit a patch to add '-p python3' to that line?

Are there any downsides to enforcing that the virtualenv used for the
documentation build use python3 only?

Thanks,
-- Tim

Gory details:
I'm running on a machine with Ubuntu 16.04, and I have both python2 and
python3 installed (with /usr/bin/python linked to python2.7).

When I tried to do:
$ make htmldocs
I got the following messages:
...
You should run:

sudo apt-get install dvipng fonts-noto-cjk latexmk librsvg2-bin texlive-xetex

/usr/bin/virtualenv sphinx_1.7.9
. sphinx_1.7.9/bin/activate
pip install -r ./Documentation/sphinx/requirements.txt
If you want to exit the virtualenv, you can use:
deactivate
---
Following these instructions, at the 'pip install' step, I got:
$ pip install -r ./Documentation/sphinx/requirements.txt
DEPRECATION: Python 2.7 reached the end of its life on January 1st, 2020. Please upgrade your Python as Python 2.7 is no longer maintained. A future version of pip will drop support for Python 2.7. More details about Python 2 support in pip, can be found at https://pip.pypa.io/en/latest/development/release-process/#python-2-support
Collecting docutils
Downloading docutils-0.16-py2.py3-none-any.whl (548 kB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 548 kB 2.2 MB/s
Collecting Sphinx==1.7.9
Downloading Sphinx-1.7.9-py2.py3-none-any.whl (1.9 MB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 1.9 MB 30.7 MB/s
Collecting sphinx_rtd_theme
Downloading sphinx_rtd_theme-0.4.3-py2.py3-none-any.whl (6.4 MB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 6.4 MB 25.6 MB/s
Collecting alabaster<0.8,>=0.7
Downloading alabaster-0.7.12-py2.py3-none-any.whl (14 kB)
Collecting Pygments>=2.0
Downloading Pygments-2.5.2-py2.py3-none-any.whl (896 kB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 896 kB 35.1 MB/s
Collecting Jinja2>=2.3
Downloading Jinja2-2.11.1-py2.py3-none-any.whl (126 kB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 126 kB 26.2 MB/s
Collecting requests>=2.0.0
Downloading requests-2.23.0-py2.py3-none-any.whl (58 kB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 58 kB 774 kB/s
Collecting packaging
Downloading packaging-20.1-py2.py3-none-any.whl (36 kB)
Collecting snowballstemmer>=1.1
Downloading snowballstemmer-2.0.0-py2.py3-none-any.whl (97 kB)
|â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^â-^| 97 kB 1.1 MB/s
Collecting sphinxcontrib-websupport
Downloading sphinxcontrib_websupport-1.1.2-py2.py3-none-any.whl (39 kB)
Requirement already satisfied: setuptools in ./sphinx_1.7.9/lib/python2.7/site-packages (from Sphinx==1.7.9->-r ./Documentation/sphinx/requirements.txt (line 2)) (45.0.0)
ERROR: Package 'setuptools' requires a different Python: 2.7.12 not in '>=3.5'