Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula <jani.nikula@linux.intel.com>]

On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 07.11.2016 um 18:01 schrieb Josh Triplett <josh@joshtriplett.org>:
>
>> 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