Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751093AbdFSOWO (ORCPT ); Mon, 19 Jun 2017 10:22:14 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:44742 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1750811AbdFSOWN (ORCPT ); Mon, 19 Jun 2017 10:22:13 -0400 Date: Mon, 19 Jun 2017 11:21:58 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Christoph Hellwig , Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Greg Kroah-Hartman , SeongJae Park , Markus Heiser , Masahiro Yamada , Max Filippov Subject: Re: [PATCH] changes.rst: explain the usage of virtual environment Message-ID: <20170619112158.1a609063@vento.lan> In-Reply-To: <20170619074653.4fbcdd36@lwn.net> References: <736d4f4128feaf09f0de91e665dd0666ffa07a18.1497870046.git.mchehab@s-opensource.com> <20170619130837.GA25524@infradead.org> <20170619074653.4fbcdd36@lwn.net> Organization: Samsung X-Mailer: Claws Mail 3.14.1 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 1814 Lines: 47 Em Mon, 19 Jun 2017 07:46:53 -0600 Jonathan Corbet escreveu: > On Mon, 19 Jun 2017 06:08:37 -0700 > Christoph Hellwig wrote: > > > On Mon, Jun 19, 2017 at 08:24:10AM -0300, Mauro Carvalho Chehab wrote: > > > As the Sphinx build seems very fragile, specially for > > > PDF output, add a notice about how to use it on a virtual > > > environment. > > > > Please don't. python venv are good at one thing only, and that is > > making a mess of your python module path. Don't ever use them on a > > system that has proper package management. > > Well, they are also good for running specific versions of a given package > without disrupting the setup of your system as a whole, and when even a > system with proper package management may not offer the version you need. Yes. Based on my experience with Sphinx, upgrading it to a new version is painful, as it can cause regressions on docs build. Also, when a new version is released, the previously stable version becomes abandoned. Not even trivial and/or compatibility fixes are accepted against old versions. So, at least for me, it works best if an specific version is installed inside a virtual environment, as it won't cause problems when I update other packages on my distro. The one I'm using here is version 1.4.9 (the latest 1.4.x version). Right now, vesion 1.5.x require a series of patches from Jon to fix PDF build, and more stuff will be needed to fix PDF builds with 1.6.x. > I guess my question with the patch is whether this text really belongs in > changes.rst, or whether it should be part of the doc-guide. Jon, If you prefer, I can move such description to doc-guide, but I suspect that we may need to specify, at changes.rst, what Sphinx versions are known to work fine. Thanks, Mauro