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

[Laurent Pinchart]

Hi Kieran,

On Friday, 14 December 2018 15:20:35 EET Kieran Bingham wrote:
> On 14/12/2018 09:37, Laurent Pinchart wrote:
> > 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 ?

We already require 0.40 while Debian ships 0.37. Debian testing has 0.48, so 
does gentoo, and Ubuntu ships 0.47. The previous Ubuntu release shipped 0.45 
though. I'm tempted to say we could bump the minimum version to 0.47, but I 
may be a rushing it a bit. What do you think ?

-- 
Regards,

Laurent Pinchart