Re: [PATCH] changes.rst: explain the usage of virtual environment

[Markus Heiser]

> Am 19.06.2017 um 16:38 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
> 
> HI Markus,
> 

Hi Mauro :)

[...]

>> 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).

I will take this in mind.

> 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.

good point ;)

>> ..
>> 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?

No, with @$(PY_ENV_BIN)/pip you always use the pip from the environment
and this is always named pip. E.g::

 ./local/py3/bin/pip
 ./local/py2/bin/pip

Or: same as "sphinx-build" command .. there is no sohinx-build3 ;)

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

right, the above was only a sloppily C&P from what I have in my project.

>> ..
>> 
>> 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.

OK, I will prepare a RFC patch ... I will have time for this only on the
weekend, so have some patience with me.

-- Markus --