Re: [PATCH 00/18] Complete moving media documentation to ReST format

[Markus Heiser <markus.heiser@darmarit.de>]

Am 21.07.2016 um 01:28 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Wed, 20 Jul 2016 08:07:54 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Jon, what do you think ... could we serve this 1.2 doc 
>> on https://www.kernel.org/doc/ as reference?
> 
> Seems like a good idea.  I don't really know who controls that directory,
> though; I can ping Konstantin and see what can be done there.  Failing
> that, I'd be more than happy to put it up on lwn, of course.
> 
>> And whats about those who have 1.3 (or any version >1.2) as default 
>> in the linux distro? Should they install a virtualenv?  ... it is
>> a dilemma.
> 
> I would hope that most people wouldn't have to worry about it, and would
> be able to just use what their distribution provides - that's the reason
> for the 1.2 compatibility requirement in the first place.

Yes, but this is not what I mean ;) ... if someone use a distro 
with a version > 1.2 and he use features not in 1.2, you -- the
maintainer -- will get into trouble. 

IMHO contributors need a reference documentation (e.g. at kernel.org)
and a reference build environment (like you, see below).

> I'll make a
> point of having a 1.2 installation around that I can test things with;
> that should suffice to catch any problems that sneak in.

This is what I called the reference build environment. IMHO a 
ref build env could only be assert by a virtualenv instance.

Here is what I tried to get one  ....

first: create instance:

 $ virtualenv /share/sph12env

second: source the virtualenv

 $ source /share/sph12env/bin/activate
 $ which pip
 /share/sph12env/bin/pip

third: install Sphinx 1.2

$ pip install Sphinx==1.2
$ sphinx-build --version
Sphinx (sphinx-build) 1.2

seems fine ... now install rtd theme :-o

$ pip install sphinx_rtd_theme==0.1.8
Collecting sphinx_rtd_theme==0.1.8
 Downloading sphinx_rtd_theme-0.1.8-py2.py3-none-any.whl (418kB)
Collecting sphinx>=1.3 (from sphinx_rtd_theme==0.1.8)
...

since sphinx>=1.3 is a requirement [1] of the sphinx_rtd_theme package
sphinx has been updated:

$ sphinx-build --version
Sphinx (sphinx-build) 1.4.5

Aaargh ... at the least now, I have strong doubts if it is a clever
decision to use an old sphinx version as reference.

Lets lean back and remember why we need this ... whatever
sphinx version a distro ships (with it's next update) you need a
reference environment ... version 1.2 or the latest version ... equal 
if you are a maintainer or a contributor ...  

So why not installing a updated version in a virtualenv on the build
server, may be in a jail. If contributors have installed older versions,
this is not a problem, the updated one is downward compatible.

[1] https://github.com/snide/sphinx_rtd_theme/blob/0.1.8/requirements.txt

-- Markus --