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]

Date:   Fri, 11 Nov 2016 07:34:47 -0200
From:   Mauro Carvalho Chehab <m.chehab@...sung.com>
To:     Jani Nikula <jani.nikula@...ux.intel.com>
Cc:     Markus Heiser <markus.heiser@...marit.de>,
        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

Em Wed, 09 Nov 2016 13:58:12 +0200
Jani Nikula <jani.nikula@...ux.intel.com> escreveu:

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

I agree with Jani here: copy the files will make Sphinx recompile
the entire documentation every time, with is bad. Ok, Some Makefile
logic could be added to copy only on changes, but that will increase
the Makefile complexity.

So, I prefer not using copy. As I said before, a Sphinx extension that
would make transparent for PDF document generation when a non-PDF image
is included, doing whatever conversion needed, seems to be the right fix 
here, but someone would need to step up and write such extension.

-- 

Cheers,
Mauro