Em Tue, 19 Jul 2016 14:31:18 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > > I really hate stupid toolchains that require everybody to upgrade to > > the very latest version of it every time. > > Hi Mauro, > > It might be annoying how sphinx handles errors, but normally a build > process should report errors to monitor. The documents are automatically built at linuxtv.org once a day. While Sphinx doesn't build them without warnings, I won't enable any sort of feedback from the server, as I don't want to be bothered all days about the same warnings. Also, for safety reasons, we only install packages on the server that are shipped with the distribution. > > Maybe someone at linux-doc > > may have an idea about how to add new markup attributes to the > > documents without breaking for the ones using older versions of Sphinx. > > see below > > > The problem we're facing is due to a change meant to add a title before > > each media's table of contents (provided via :toctree: markup). > > I think this is only ONE drawback, others see the changelog .. I had to remove captions from tables on a past patch, because of the same reason: Sphinx 1.2.x doesn't support it. > * http://www.sphinx-doc.org/en/stable/changes.html 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. > > All it needs is something that will be translated to HTML as: > > <h1>Table of contents</h1>, without the need of creating any cross > > reference, nor being added to the main TOC at Documentation/index.rst. > > > > We can't simply use the normal way to generate <h1> tags: > > > > --- a/Documentation/media/dvb-drivers/index.rst > > +++ b/Documentation/media/dvb-drivers/index.rst > > @@ -15,6 +15,10 @@ the license is included in the chapter entitled "GNU Free Documentation > > License". > > > > > > +##################### > > +FOO Table of contents > > +##################### > > + > > .. toctree:: > > :maxdepth: 5 > > :numbered: > > > > The page itself would look OK, but this would produce a new entry at the > > output/html/index.html: > > > > * Linux Digital TV driver-specific documentation > > * FOO Table of contents > > > > 1. Introdution > > > > With is not what we want. > > > > With Sphinx 1.4.5, the way of doing that is to add a :caption: tag > > to the toctree, but this tag doesn't exist on 1.2.x. Also, as it > > also convert captions on references, and all books are linked > > together at Documentation/index.rst, it also needs a :name: tag, > > in order to avoid warnings about duplicated tags when building the > > main index.rst. > > > > I have no idea about how to do that in a backward-compatible way. > > > > Maybe Markus, Jani or someone else at linux-doc may have some > > glue. > > IMHO: A backward-compatible way for all linux distros and versions > out there is not the way. > > If we use options or features of a new version, we have to > install the new version (independent which xml we used in the past > or python tool we want to use). With DocBook this is clear: the document itself is bound against an specific version of the spec. So, *all* versions of the DocBook toolchains support the very same document, or, when it doesn't, the toolchain aborts with an error and doesn't produce anything. Very easy for a script to identify if the build succeeds or not. Sphinx is very evil with that regards: it keeps generating the files, except that the contents of the tags that contain unrecognized fields will be empty (with is very bad for :toctree:) and a few additional warnings will be generated. Very hard for a script to detect if the doc was OK or got mangled by the toolchain, because of a version incompatibility. > IMHO the main problem is, that we have not yet documented on which > Sphinx version we agree and how to get a build environment which > fullfills these requirements. Yes, the Sphinx minimal version should be documented at Documentation/Changes. I'd say that the minimal version should be the Sphinx version found on the latest version of the main distributions, e .g. at least Fedora, openSuse, Debian, Ubuntu. (I guess distros like ArchLinux and Gentoo won't be a problem, as they tend to use the newer versions of the sources). On a quick check: - Fedora 24 comes with 1.3.x - openSuse 13.2 with 1.2.x - Debian 8.5 with 1.2.x. - Ubuntu 16.04 with 1.3.x - Ubuntu 14.04 with 1.2.x - Mageia 5 with 1.2.x So, I guess we should set the minimal requirement to 1.2.x. Btw, usually, on Kernel, we're very conservative to increment the minimal version of a toolchain. So, for example, while GCC current version is 6.1, the minimal requirement is gcc 3.2 (with was released in 2003). > For build environments I recommend to set up a python virtualenv > > * https://virtualenv.pypa.io/en/stable/ We can't assume that every Kernel developer would install a python virtualenv. Instead, they'll just use whatever Sphinx version is provided on their development machines. > Additional: > > At this time, the make file only checks if sphinx is installed. > With a small addition to the make file, we could check if all > requirements are fulfilled. > > If you are interested in how, I could send a patch. It is better to have an error than to build the documentation with errors. Yet, as I said, this doesn't fix the issue, as anyone can insert a tag that won't be recognized by the official minimal version. Not sure how to address this. Yet, this doesn't solve the specific issue for the TOC index name. How this could be done in a way that would be backward compatible to 1.2.x? 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
