Em Wed, 20 Jul 2016 08:07:54 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > Am 20.07.2016 um 02:00 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > > > Em Tue, 19 Jul 2016 16:49:16 -0600 > > Jonathan Corbet <corbet@xxxxxxx> escreveu: > > > >> On Tue, 19 Jul 2016 11:53:19 -0300 > >> Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > >> > >>> So, I guess we should set the minimal requirement to 1.2.x. > >> > >> *sigh*. > >> > >> I hate to do that; things are happening quickly enough with Sphinx that > >> it would be nice to be able to count on a newer version. That said, one > >> of my goals in this whole thing was to make it *easier* for developers to > >> generate the docs; the DocBook toolchain has always been notoriously > >> difficult in that regard. Forcing people to install a newer sphinx by > >> hand is not the way to get there. > >> > >> So I guess we need to make sure things work with 1.2 for now. I'd hope > >> we could push that to at least 1.3 before too long, though, once the > >> community distributions are there. I think we can be a *bit* more > >> aggressive with the docs than with the kernel as a whole. > > > > Yeah, that seems to be the right strategy, IMHO. With the patch I sent, > > the media books will again build fine with 1.2. > > > It is a difficult situation, whatever we do, we will get in trouble. To > handle this, (IMHO) at first we need a reference documentation. > > > What we miss is the documentation for Sphinx 1.2 and 1.3 versions. The > > site only has documentation for the very latest version, making harder > > to ensure that we're using only the tags supported by a certain version. > > We could build the documentation of the (e.g.) 1.2 tag > > https://github.com/sphinx-doc/sphinx/tree/1.2 > > by checkout the tag, cd to "./doc" and run "make html". > I haven't tested yet, but it should work this way. > > Jon, what do you think ... could we serve this 1.2 doc > on https://www.kernel.org/doc/ as reference? Yeah, building the documentation for 1.2.3 worked. I added the documentation at linuxtv.org: https://linuxtv.org/downloads/sphinx-1.2.3/ Yet, I agree that the best would be to host it at kernel.org, and add a link for it at kernel-documentation.rst. > 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. Well, they won't notice if a newer tag is used. IMHO, the best would be if we had some tag at the configuration file or at the book itself that would specify the sphinx version, and produce an ERROR if a tag for newer versions would be used. Not having that means more work for maintainers, as we'll need to check it when merging patches for documentation. > > Sorry that I have not identified this earlier ... I'am using python > a long time and for me it is common to set up build processes > with a version decoupled from the OS version, mostly the up to date > version .. thats why I have neglected any version problems :( > > -- Markus -- > > > > > > > Thanks, > > Mauro > Thanks, Mauro -- 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
