Re: [ft-devel] Integrating Docwriter into FreeType

[Werner LEMBERG]

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

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

> 1. Check if `pip' is installed (not sure how in a makefile). If not,
>    fail with an error.

Nope.  Let's follow the behaviour of `configure' scripts which also
abort but don't do any installation.

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

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

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

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


    Werner