Hmm. `make refdoc' is not a target that is to be called by Joe User.
It was always handled specially, i.e., it was assumed, for example,
that Python is available, without testing for its existence.
True. I'm not sure if we should shift the responsibility of creating a
virtualenv to the user though.
In any case, we must ensure `pip' is available.
> I don't want those packages to pollute my environment, if I just
> want to build the freetype documentation.
>
> You should either exit with error if the requirements are not met,
> and maybe tell the user to run pip install -r requirements.txt for
> themselves;
Yes. Nikhil, please replace the call to `pip install' with a check
whether the necessary packages are available, emitting a list of
packages that the user has to install to proceed.
We can either do what you suggest or the following:
1. Check if `pip' is installed (not sure how in a makefile). If not, fail
with an error.
2. Install `virtualenv' using `pip' (as Cosimo suggested), and create
and activate one.
3. Call the remaining commands to ensure all the requirements are
installed with correct versions.
This will safely generate the docs and also not pollute user's packages.
There is a problem with this though:
Unix and Windows systems have different commands to activate a
virtualenv.
What do you think?
> or you could bootstrap a new python virtual environment, [...]
I don't have an opinion here since I'm not Python user. My gut
feeling, however, says that we should first try to make it run with
installed packages also.
This approach means running a simple import check with the required
packages and only telling the user about the missing ones. Then again,
we cannot expect a user to have packages like `mkdocs' so we have to
almost always install those packages for them.
> This would also avoid issues like the one Werner reported where
> there is a conflict between the version of Pygments installed
> globally (via the distro package manager) and the one required by
> the docwriter.
Hmm, I don't see a version test for Pygments in `requirements.txt'.
Nikhil?
Like Cosimo says, this is a requirement for one of the requirements.