Em Tue, 19 Jul 2016 11:19:11 +0200 Hans Verkuil <hverkuil@xxxxxxxxx> escreveu: > > All those documents are built automatically, once by day, at linuxtv.org: > > > > uAPI: > > https://linuxtv.org/downloads/v4l-dvb-apis-new/media/media_uapi.html > > Erm, there is nothing there, only the top-level menu. Gah! The problem is due to the Sphinx version. I added a patch yesterday adding a caption to each book's toctree. This doesn't work with the Sphinx version at the server (1.2.3). Instead of ignoring the option, Sphinx decided to just drop the entire tag, with actually means to drop all media pages! I really hate stupid toolchains that require everybody to upgrade to the very latest version of it every time. 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. 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). 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. In the mean time, I attached a patch that the server applies before building the documentation. Thanks, Mauro doc-rst: Don't use :caption: or :name: tags for media documents If Sphinx version is lower than 1.4.x (I tested with 1.4.5), this patch is needed for it to build, as otherwise Sphinx will ignore the toctable markups and won't build the media documentation, creating just an empty page. Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> diff --git a/Documentation/media/dvb-drivers/index.rst b/Documentation/media/dvb-drivers/index.rst index e1d4d87f2a47..0e065533beb6 100644 --- a/Documentation/media/dvb-drivers/index.rst +++ b/Documentation/media/dvb-drivers/index.rst @@ -18,8 +18,6 @@ License". .. toctree:: :maxdepth: 5 :numbered: - :caption: Table of Contents - :name: dvb_mastertoc intro avermedia diff --git a/Documentation/media/media_kapi.rst b/Documentation/media/media_kapi.rst index 0af80e90b7b5..556c0eb55c85 100644 --- a/Documentation/media/media_kapi.rst +++ b/Documentation/media/media_kapi.rst @@ -17,8 +17,6 @@ License". .. toctree:: :maxdepth: 5 :numbered: - :caption: Table of Contents - :name: kapi_mastertoc kapi/v4l2-framework kapi/v4l2-controls diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst index debe4531040b..aae8124defcc 100644 --- a/Documentation/media/media_uapi.rst +++ b/Documentation/media/media_uapi.rst @@ -17,8 +17,6 @@ License". .. toctree:: :maxdepth: 5 - :caption: Table of Contents - :name: uapi_mastertoc intro uapi/v4l/v4l2 diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 8d1710234e5a..b9c9c0911db9 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -18,8 +18,6 @@ License". .. toctree:: :maxdepth: 5 :numbered: - :caption: Table of Contents - :name: v4l_mastertoc fourcc v4l-with-ir -- 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
