[libcamera-devel] [PATCH] Documentation: Add linkcheck target

[Kieran Bingham]

Hi Laurent,

On 14/12/2018 09:37, Laurent Pinchart wrote:
> Hi Kieran,
> 
> Thank you for the patch.
> 
> On Friday, 14 December 2018 11:01:01 EET Kieran Bingham wrote:
>> Sphinx provides a run-target to verify external links specified in the
>> documentation. This requires an active connection to be able to validate
>> the links.
>>
>> Add a meson target to integrate the linkcheck facility into our build
>> and test system.
>>
>> This rule does not run by default, but can be called with:
>>
>>   ninja Documentation/linkcheck
>>
>> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
>> ---
>>  Documentation/meson.build | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/Documentation/meson.build b/Documentation/meson.build
>> index dd43b2cbd401..cf91202224db 100644
>> --- a/Documentation/meson.build
>> +++ b/Documentation/meson.build
>> @@ -55,4 +55,9 @@ if sphinx.found()
>>                    build_by_default: true,
>>                    install: true,
>>                    install_dir: doc_install_dir)
>> +
>> +    custom_target('documentation-linkcheck',
> 
> What's the use of the first argument by the way, given that ninja seems to use 
> the target directory only as target specifiers ?

As far as I can tell - it's only use is as the string that gets
displayed to show what stage is running.

> 
>> +                  command: [sphinx, '-W', '-b', 'linkcheck',
>> meson.current_source_dir(), '@OUTPUT@'],
>> +                  input: docs_sources,
>> +                  output: 'linkcheck')
> 
> Does this create any file in the linkcheck directory ? Will it be re-run every 
> time it is manually invoked ? I think it should be, as there's a use case for 
> checking links without modifying the source files.

Yes, it does create some files in the output - but currently - it does
not re-run if it has already run successfully.

Here we have a pickle - as the 'correct' fix for this was only
introduced in meson 0.47.

https://mesonbuild.com/Release-notes-for-0-47-0.html#deprecated-build_always-for-custom-targets

The correct solution is to add 'build_always_stale: true,' to the custom
target.

Adding 'build_always' will make it always rebuild, but also include it
in the main 'ninja' build, which I don't want to do with this target.

So we can either leave this out - (we are currently on a minimum meson
build 0.40) - or bump up our minimum version requirements ...

What do you think ?

--
Kieran


> 
>>  endif
> 

-- 
Regards
--
Kieran