> In any case, we must ensure `pip' is available.
Yes. But packages should *not* be installed by the script but by the
user. I think something like the following might work.
1. Check whether all needed modules are available, ideally using a
simple solution that doesn't need `pip'. No need to test secondary
dependencies – if package `foo', version x.y is installed, simply
assume that it really works.
There isn't a way to check if a package of a specific version is installed
without pip. What could be done:
1. Check if pip is installed. If not, throw error requiring pip.
2. If yes, go on and check if other required packages with their specific
versions are installed. Throw error with instructions on how to install the
required packages.
3. Continue with generating docs normally if everything is found.
(Note that this is only in case user is not using a virtualenv, so we are
assuming that we are working with the user's python packages).
2. Collect a list of all (top-level) modules that are missing. `make'
should abort with an error if something is missing, displaying this
list. The error message should show a helpful text how the user
can install missing stuff. IMHO it is not necessary to address
novices here; whoever is going to call `make refdoc' has certainly
enough knowledge to install Python modules (and google is your
friend otherwise)...
This will require a python script - to check if all modules are available
and display a helpful error text.
> 2. Install `virtualenv' using `pip' (as Cosimo suggested), and
> create and activate one.
Again, this might be discussed in the README file, but I don't want to
have this automatically installed by the Makefile. There might be a
different Makefile target, say, `make refdoc-virtualenv' (with any
additional parameters if necessary) that uses `virtualenv'. [This is
just an educated guess; no idea whether this is necessary or useful.]
The `make refdoc-venv` or equivalent will be the easiest way to build the docs
because that will create a virtualenv, install all required packages in it and
build docs. All this without touching the user's python configuration.
The only requirement for this is availability of pip and virtualenv.
> Unix and Windows systems have different commands to activate a
> virtualenv.
How unfortunate. Following my thoughts above, this could be handled
by, say
make refdoc-virtualenv unix
make refdoc-virtualenv windows
On the other hand, FreeType's build ecosystem already identifies Unix
and Windows boxes, so perhaps this can be handled automatically.
Yes, this is possible. I can add a variable for the `bin' and the `Scripts' folder
in unix and windows so that a single command will work for both boxes.
> 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.
As written above: The Makefile shouldn't do any python package
installation.
Except in the case of virualenv, because doing that is completely safe.
>> 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.
Then this package (which one, BTW?) isn't set up correctly, obviously
containing a too low minimum version since it doesn't work with
Pygments 2.1.3 which I have on my computer. This should be reported
as a bug – or am I missing something?
The upstream package might have an issue with the newer versions of
Pygments, which may not have been fixed yet. This is mainly why using
a virtualenv is always recommended.