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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87shr0g90r.fsf@intel.com>
Date:   Wed, 09 Nov 2016 13:58:12 +0200
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Markus Heiser <markus.heiser@...marit.de>
Cc:     Josh Triplett <josh@...htriplett.org>,
        Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org,
        linux-media@...r.kernel.org,
        ksummit-discuss@...ts.linuxfoundation.org,
        linux-doc@...r.kernel.org
Subject: Re: [Ksummit-discuss] Including images on Sphinx documents

On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@...marit.de> wrote:
> Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nikula@...ux.intel.com>:
>>> 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.
>
> ... new ones? ...

Handle in-tree builds without copying.

Make dependency analysis with source rst and "intermediate" rst work.

Make sure your copying gets the timestamps right.

Make Sphinx dependency analysis look at the right copies depending on
in-tree vs. out-of-tree. Generally make sure it doesn't confuse Sphinx's
own dependency analysis.

The stuff I didn't think of.

Sure, it's all supposed to be basic Makefile stuff, but don't make the
mistake of thinking just one invocation of 'cp' will solve all the
problems. It all adds to the complexity we were trying to avoid when
dumping DocBook. It adds to the complexity of debugging stuff. (And hey,
there's still the one rebuilding-stuff-for-no-reason issue open.)

If you want to keep the documentation build sane, try to avoid the
Makefile preprocessing. And same old story, if you fix this for real,
even if as a Sphinx extension, *other* people than kernel developers
will be interested, and *we* don't have to do so much ourselves.

BR,
Jani.

>
>>> 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 --

-- 
Jani Nikula, Intel Open Source Technology Center