On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > Am 07.11.2016 um 18:01 schrieb Josh Triplett <josh@xxxxxxxxxxxxxxxx>: > >> 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@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Jani Nikula, Intel Open Source Technology Center -- 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
