Re: [PATCH RFC] scripts/sphinx-pre-install: add a script to check Sphinx install

[Markus Heiser]

> Am 15.07.2017 um 04:21 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
> 
> Em Fri, 14 Jul 2017 19:35:59 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> 
>>> Am 14.07.2017 um 18:49 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>>> 
>>> Solving Sphinx dependencies can be painful. Add a script to
>>> check if everything is ok.  
>> 
>> just my 5cent:
>> 
>> What we need is a "requirements.txt" file to define a
>> **reference environment**. E.g. to stick Sphinx 1.4.9 in
>> such a reference environment::
>> 
>> <snip: requirements.txt> ---
>> Sphinx==1.4.9
>> sphinx_rtd_theme
>> <snap> ---------------------
>> 
>> The rest is similarly to what you wrote in doc-guide/sphinx.rst ...
>> 
>> The ref-environment can be build with virtualenv & pip::
>> 
>> $ virtualenv --python=python3 docenv
>> (doc-env) $ source ./docenv/bin/activate
>> (doc-env) $ pip install -r requirements.txt
>> 
>> From now we can start our build as usual. If not already done,
>> first activate the environment::
>> 
>> $ . ./docenv/bin/activate
>> (doc-env) $ make htmldocs
>> 
>> This (requirements.txt) is the way python packaging goes.
> 
> 
> The above assumes that the user wants to use virtenv and
> have python3, virtualenv3 and pip3 already installed.
> 
> I agree that a virtual environment works better than using
> distro-specific packaging, as Sphinx toolchain is really
> fragile. But we should give an option for the developer to
> use whatever he wants.

The developer is free to choose the way he like. But we are talking
about what is "best practice".

I tested sphinx-pre-install and it works fine for me, thats not the
point. The point is: what do we recommend? E.g. for me it advices me
to run:

	sudo apt-get install python3-sphinx python3-sphinx-rtd-theme

We should not assume that the developer (better: the build-user) owns the
privilege to install fine grained OS packages. There is a admin-part and
a user-part:

The admin (sudoer) installs binaries into the OS:

* gcc
* make
* python3, virtualenv
* LiveTex
* ImageMagick
* perl
* graphviz

The user (developer) installs additional requirements anywhere
under $HOME:

* Python 

  best practice here is virtualenv and pip .. and the *recipe*
  to get a *reference environment* is the requirements.txt
 
* LaTeX

  what is best practice here? .. I know there is some package
  managing with "TeX Live Manager" (tlmgr) but I have no experience
  with. Is there a way to define a *requirements* file and
  to install such requirements anywhere under $HOME?

My english is less eloquent, but I hope its clear what I mean.

To have a script is nice, but first lets explore what best practice
is.


-- Markus --