Am 21.07.2016 um 01:28 schrieb Jonathan Corbet <corbet@xxxxxxx>: > On Wed, 20 Jul 2016 08:07:54 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> 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 -- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
