From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 99355415 for ; Wed, 9 Nov 2016 11:16:59 +0000 (UTC) Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id C4925297 for ; Wed, 9 Nov 2016 11:16:58 +0000 (UTC) From: Jani Nikula To: Markus Heiser , Josh Triplett In-Reply-To: References: <20161107075524.49d83697@vento.lan> <20161107170133.4jdeuqydthbbchaq@x> Date: Wed, 09 Nov 2016 13:16:55 +0200 Message-ID: <8737j0hpi0.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Cc: ksummit-discuss@lists.linuxfoundation.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , linux-media@vger.kernel.org Subject: Re: [Ksummit-discuss] Including images on Sphinx documents List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , On Wed, 09 Nov 2016, Markus Heiser wrote: > Am 07.11.2016 um 18:01 schrieb Josh Triplett : > >> On Mon, Nov 07, 2016 at 07:55:24AM -0200, Mauro Carvalho Chehab wrote: >>> 2) add an Sphinx extension that would internally call ImageMagick and/or >>> inkscape to convert the bitmap; >> >> This seems sensible; Sphinx should directly handle the source format we >> want to use for images/diagrams. >> >>> 3) if possible, add an extension to trick Sphinx for it to consider the >>> output dir as a source dir too. >> >> Or to provide an additional source path and point that at the output >> directory. > > The sphinx-build command excepts only one 'sourcedir' argument. All > reST files in this folder (and below) are parsed. > > Most (all?) directives which include content like images or literalinclude > except only relative pathnames. Where *relative* means, relative to the > reST file where the directive is used. For security reasons relative > pathnames outside 'sourcepath' are not excepted. > > So I vote for : > >> 1) copy (or symlink) all rst files to Documentation/output (or to the >> build dir specified via O= directive) and generate the *.pdf there, >> and produce those converted images via Makefile.; We're supposed to solve problems, not create new ones. > Placing reST files together with the *autogenerated* (intermediate) > content from > > * image conversions, > * reST content build from MAINTAINERS, > * reST content build for ABI > * etc. > > has the nice side effect, that we can get rid of all theses BUILDDIR > quirks in the Makefile.sphinx > > Additional, we can write Makefile targets to build the above listed > intermediate content relative to the $PWD, which is what Linux's > Makefiles usual do (instead of quirking with a BUILDDIR). > > E.g. with, we can also get rid of the 'kernel-include' directive > and replace it, with Sphinx's common 'literaliclude' and we do not > need any extensions to include intermediate PDFs or whatever > intermediate content we might want to generate. Well, kernel-include is a hack to make parse-headers.pl work, which is also a hack that IMHO shouldn't exist... > IMO placing 'sourcedir' to O= is more sane since this marries the > Linux Makefile concept (relative to $PWD) with the sphinx concept > (in or below 'sourcedir'). > > > -- Markus -- > > > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Jani Nikula, Intel Open Source Technology Center