Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Wed, 4 Mar 2020 20:53:05 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To:     "Bird, Tim" <Tim.Bird@sony.com>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        "tbird20d@gmail.com" <tbird20d@gmail.com>,
        "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH] scripts/sphinx-pre-install: add '-p python3' to
 virtualenv
Message-ID: <20200304205252.51bac986@coco.lan>
In-Reply-To: <MWHPR13MB08952CDE2E8F16781B704C18FDE50@MWHPR13MB0895.namprd13.prod.outlook.com>
References: <1582594481-23221-1-git-send-email-tim.bird@sony.com>
        <20200302130911.05a7e465@lwn.net>
        <MWHPR13MB0895EFDA9EBF7740875E661CFDE40@MWHPR13MB0895.namprd13.prod.outlook.com>
        <20200303130152.461c3494@lwn.net>
        <MWHPR13MB08952CDE2E8F16781B704C18FDE50@MWHPR13MB0895.namprd13.prod.outlook.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Wed, 4 Mar 2020 17:25:41 +0000
"Bird, Tim" <Tim.Bird@sony.com> escreveu:

> > -----Original Message-----
> > From: Jonathan Corbet <corbet@lwn.net>
> > 
> > On Tue, 3 Mar 2020 17:07:48 +0000
> > "Bird, Tim" <Tim.Bird@sony.com> wrote:
> >   
> > > The less fragile approach would have been to just
> > > always add the '-p python3' option to the virtualenv setup hint,
> > > but Mauro seemed to want something more fine-tuned.  
> > 
> > At some point I think we'll want to say that Python 2 just isn't supported
> > anymore.  After all, the language itself isn't supported anymore.  Perhaps
> > it's time to add a warning somewhere.  
> 
> Probably.  IMHO always adding the 'p python3' would have been the
> first vestiges of such a hint, but maybe it should be more explicit.
> A more explicit statement of "watch out if your default python
> interpreter is python2" would have probably shortened some of 
> my setup time.

A warning like that makes sense to me.

> Ubuntu 16.04 and Ubuntu 18.04 both include python3, but have
> /usr/bin/python default to python2.  So, while the package recommendations
> from the script were good (and sufficient), the virtualenv hint was somewhat
> lacking.

And if you try to change the Ubuntu default to python3, some things break 
there (I did that last month using alternates on Ubuntu 19.10 - had to 
revert back to python2).

> And, just for full disclosure, I wish there was a way to mark this type of fix
> with a obsolescence  flag so it could be removed later.  This is the type of
> thing that gets put into a script as a workaround for a transition period, but
> keeps being run 10 years later when it's no longer relevant.  Heck, the whole
> virtualenv recommendation might be irrelevant in the next version of Ubuntu
> (but maybe the script already figures that out.)

Actually, virtualenv support was added later ;-)

The script supports both virtualenv and distro package install, although
the current default is to use virtualenv. You can force it to recommend the
distro package with:

	$ ./scripts/sphinx-pre-install --no-virtualenv
	Detected OS: Fedora release 30 (Thirty).

	ERROR: please install "python-sphinx", otherwise, build won't work.
	Warning: better to also install "sphinx_rtd_theme".
	You should run:

		sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme

	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 721.

The main reason why virtualenv is the default is that we need to
ensure a certain minimal version (nowadays, it is recommended at least 1.7.9). 
If one is using a LTS distro, the distro-package could be older than that.

With virtualenv, it is easier to fulfill the minimal version (and the
recommended one). You may even have multiple Sphinx versions, with is
quite useful when trying to identify if the html and/or pdf output
is doing the right thing with different toolchain versions.

Thanks,
Mauro