Date: Mon, 19 Jun 2017 11:38:01 -0300
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>,
        Christoph Hellwig <hch@infradead.org>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@infradead.org>,
        "linux-kernel@vger.kernel.org org List" 
        <linux-kernel@vger.kernel.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        SeongJae Park <sj38.park@gmail.com>,
        Masahiro Yamada <yamada.masahiro@socionext.com>,
        Max Filippov <jcmvbkbc@gmail.com>
Subject: Re: [PATCH] changes.rst: explain the usage of virtual environment
Message-ID: <20170619113801.6b2f21dc@vento.lan>
In-Reply-To: <59B0A362-D044-4FA8-9286-6D955B8DB241@darmarit.de>
References: <736d4f4128feaf09f0de91e665dd0666ffa07a18.1497870046.git.mchehab@s-opensource.com>
        <20170619130837.GA25524@infradead.org>
        <20170619074653.4fbcdd36@lwn.net>
        <59B0A362-D044-4FA8-9286-6D955B8DB241@darmarit.de>
Organization: Samsung
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 3511
Lines: 117

HI Markus,

Em Mon, 19 Jun 2017 16:11:56 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> > Am 19.06.2017 um 15:46 schrieb Jonathan Corbet <corbet@lwn.net>:
> > 
> > On Mon, 19 Jun 2017 06:08:37 -0700
> > Christoph Hellwig <hch@infradead.org> 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.
> > 
> > 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.  
> 
> Hi, here are my 5cents:
> 
> Typically I have a PY_ENV target in my projects, building a virtualenv
> in a folder named ./local. E.g. in LinuxDoc [1] I use something like this:
> 
> 
> PY ?=3
> PYTHON ?= python$(PY)
> ..
> VIRTUALENV = virtualenv --python=$(PYTHON)
> VTENV_OPTS = "--no-site-packages"
> PY_ENV = ./local/py$(PY)

I would split the PATH name on a separate var. This way, if one would
like to have multiple Sphinx versions, all it would need would be to
change the directory.
I would prefer to call it as "./sphinx" (or something similar).

So, I would do:

  PY_DIR = ./sphinx
  PY_ENV = $(PY_DIR)/py$(PY)

Don't forget to add $PY_DIR directory to .gitignore on your patch.

> ..
> quiet_cmd_virtualenv = PYENV $@
> cmd_virtualenv = \
> 	if [ ! -d "./$(PY_ENV)" ];then \
> 	$(VIRTUALENV) $(VIRTUALENV_VERBOSE) $(VTENV_OPTS) $2; \
> 	else \
> 	echo "using virtualenv from $2"; \
> 	fi
> ...
> # to build *local* environment, python and virtualenv from the OS is needed!
> $(PY_ENV): virtualenv-exe python-exe
> 	$(call cmd,virtualenv,$(PY_ENV))
> 	@$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) -r requirements.txt

Shouldn't it be using "pip$(PY)" instead?

Also, better to seek for requirements on a file under Documentation/sphinx/
directory.

> ..
> 
> And the sphinxbuild coammand is used from there::
> 
> SPHINXBUILD ?= $(PY_ENV_BIN)/sphinx-build
> 
> By this I can stick versions packages. E.g. to select last version of
> RTD theme and Sphinx version 1.5 or upper, I add the following lines to
> my reqierements.txt::
> 
> Sphinx>=1.5  
> sphinx_rtd_theme
> 
> If you are interested, I can prepare a patch, to add such functionality 
> (as option) to Documents/Makefile (which will be documented in the doc-guide).

Yeah, IMHO, it makes sense to have something like that at the main build,
as an optional feature, e. g. perhaps adding a new make target, like:

	$ make sphinx_virtenv

That would create and populate PY_DIR. If $PY_DIR/bin/sphinx-build exists
and it is executable file, run it. Otherwise, use the system's sphinx, 
if available.

> 
> [1] https://github.com/return42/linuxdoc/blob/master/utils/makefile.python
> 
> -- Markus --
> 
> 
> 
> 
> 
> 
> > 
> > jon
> > --
> > To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html  
> 


Thanks,
Mauro