Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S934077AbcKILRC (ORCPT ); Wed, 9 Nov 2016 06:17:02 -0500 Received: from mga01.intel.com ([192.55.52.88]:62738 "EHLO mga01.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932780AbcKILQ7 (ORCPT ); Wed, 9 Nov 2016 06:16:59 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.31,614,1473145200"; d="scan'208";a="784322871" From: Jani Nikula To: Markus Heiser , Josh Triplett Cc: Mauro Carvalho Chehab , Jonathan Corbet , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org, ksummit-discuss@lists.linuxfoundation.org, linux-doc@vger.kernel.org Subject: Re: [Ksummit-discuss] Including images on Sphinx documents In-Reply-To: Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo 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 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2639 Lines: 70 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